Noah's Classifieds Documentation

Documentation For Programmers & Webmasters

All others, no worries! :) no Programming is needed to easily and successfully run Noah's Classifieds

Please note: We are working with our Documentation currently and coordinating its structure. All Information is on this page. If you find a broken link, please let us know. Thank You.

Install Requirements

(These are the minimum requirements and are very common with hosting Companies packages)

In addition to the software itself, a Noah's Classifieds installation has the following requirements:

PHP 5 is the programming language in which Noah's Classifieds is written, and is required in order to run the software. Noah's will run on any Php version above 5..
MySql 5 database server is required to store the data of the program. Noah's requires a MySql version 5. and above
A web server is required to send the generated pages to your web browser. Apache web server is recommended and is also the most common one.
IonCube Loader is required. (If you use Go Daddy, we have separate Installation Instructions for the E-Commerce Version).
Plesk Hosting is not recommended
Windows Hosting Servers or Front Page is not recommended

install.php details

The web based install wizard of Noah's Classifieds is very simple to use - it has only three steps - and you can probably go through them without reading this detailed description. The three steps are:

Step 1: Checking,
Step 2: Setup,
Step 3: Install.

Step 1: Checking

In this step, the following system requirements will be checked by the install script:

Whether the script can create (or write if already exists) the app/config.php file. This is actually not a mandatory requirement: you can create this file yourself manually and the wizard will give you every necessary guidance to do this in the further steps, but it's still easier if the install script does it! If you get a message that the install script can't create app/config.php, and you want to fix this, you can create/upload an empty config.php file into your app directory and give it enough permissions that the script can write it. If you did it, refresh the install.php in your browser to see the effect. Click here to read more about setting file permissions!
It checks if MySql exists on the server. Per default, localhost is used as the MySql server. If you have the MySql on a different server, you can still install Noah's, but you must enter than the MySql host name in Step 2,
It tries to connect to the MySql server with the root user name and without using any password. Note that even if this succeeds, from security point of view, it is strongly recommended that you use another database user than root and you access it with a password. You can set up the database user and password in Step 2

The wizard displays the following information on the screen in this step:

The results of the above checking,
The program terms and conditions,
A checkbox with which you accept the terms and conditions,
An Edit button that leads to Step 2 and/or an Install button that leads to Step3. The latter is only displayed if the script could access MySql with the given parameters.

Step 2: Setup

In this step, you can enter the necessary MySql database access details. Use localhost as the Hostname if MySql resides on your web server. You must enter an existing MySql user name! You can probably create new database users through the control panel of your server - read it's documentation about how to do it. If the database user you enter here has create database permissions, you can enter a new name as Database name and the install script will create it as a database then. More often, however, you must also create the database through the control panel before the installation.

If you submit this form, you will be forwarded to Step 1 again, and the database access will be tested with the just entered database access details. If the access fails, you can return to Step 2 again by clicking on the Edit button.

Step 3: Install

If the database connection could be successfully established, an Install button will be displayed. If you click on it, all the necessary database setup will be performed: the tables will be created and filled with some default data. Additionally, if the app/config.php file couldn't be created in Step 1, the program displays the content you have to copy/paste to create the config.php file manually. Because config.php stores the database access details, it is essential for the proper working of Noah's Classifieds that it exists in the app directory! Whether it is created by the install script, or by you manually, it has to be there, so that Noah's can use the database.

Noah's Classifieds basic installation

Below this Information are separate update instructions if you have an existing installation.

Installing Noah's Classifieds is very easy - in general it's just a matter of unpacking and following the instructions of the install wizard. However, one who has never installed a web program can still experience that it is by no means so easy as installing a simple Windows program! You should first try to follow the simple instructions given here, and if you encounter problems or the instructions are not detailed enough for you, you can follow the links to read more details about the steps.

Step 1: Check that your system meets the minimum requirements (web server, MySQL and PHP).

Step 2: Purchase and download the newest release from the Download Page.

Step 3: Unpack the distribution tarball or zip and upload/copy the files to your webspace.

Step 4: Open the install.php in your browser and follow the instructions.

Step 5: Enjoy your Noah's Classifieds install and browse through the Documentation to discover what you can do with it

Manual update

The sad truth about the automatic update is that if we really want it to work with just two single clicks, the file permissions under the Noah's installation directory have to be looser than what is recommended in security point of view! Therefore some may want to still perform the update in a “conventional” way that keeps the file permissions strict and intact. The possibility of manual update is for them. The steps of the manual update:

Step 1: Request an install package of the latest release from us by writing a support ticket,

Step 2: Unpack the update package on your computer,

Step 3: It is highly recommended that you make a backup copy of the program files before the update,

Step 4: Upload the content of the update package to your server overwriting the old files of your Noah's Classifieds installation,

Step 5: Display update.php in your browser (e.g. if your classifieds installation is under http://my_classifieds_site.com/, then put this into the browser location bar: http://my_classifieds_site.com/update.php). Click on the Update button there and the program performs the necessary database update. With this, the whole update process is completed.

Setting up file permissions

Noah's Classifieds must store the uploaded pictures and media files, writes error log and caches the RSS feed. To be able to do this, Noah's needs sufficient permissions to write these files. At the same time, leaving the permissions too loose can introduce security risks.

Noah's Classifieds is executed by PHP, so the PHP process needs to be able to write to these files. The PHP process usually runs with the permissions of the webserver, so the webserver needs to be able to write to these files.

The following permissions must be modified for the respective Noah's Classifieds functions to work:

pictures/cats and pictures/listings/ directories: all files in including the directories themselves must be writeable by the web process for Noah's Classifieds to handle image uploads.
upload directory: this directory must be writeable by the web process for the media file upload to work
feedcreator directory: this directory must be writeable by the web process for the RSS feature to work
logs directory: this directory must be writeable by the web process for the error logging to work
themes/modern/css and themes/classic/css directory: these directories must be readable by the public for style sheets to display. 755 works fine.

As admin, you can check the necessary file permissions any time by clicking on the Check menu point

During the installation, the install script attempts to create a file called config.php in the app directory - this file is used to store the database access parameters. Without this, Noah's couldn't connect to the database and would not work at all. If the install script has not enough permissions to create it, the install wizard displays the code in the browser that you must copy and paste, and you have to manually create the config.php with this content!

Unix

This will apply if you install Noah's Classifieds on a Linux, MacOS X or other Unixoid system. It is most probably also true for rented web space.

Note: under Linux additional file system ACLs (FACL) may apply, confer the commands “getfacl” and “setfacl” – file permissions as described below may be meaningless if there are no rights according to FACLs.

File Permissions, a short reminder

This is not the place to explain the UNIX file permission system in detail. See Wikipedia for this. Here is just a short refresher:

Permissions for a file are dependent of the file's owner and group and the user who tries to access the file
There are permissions for read, write and execute
Each UNIX process runs with the permissions of an OS user and his groups
The web server is a UNIX process
PHP usually runs as part of the web server
Noah's Classifieds will run with the permissions of the PHP processor
Noah's Classifieds needs read, write and execute permissions for directories it needs to create files in
Noah's Classifieds needs read and write permissions for files it needs to write to
Noah's Classifieds needs read only permissions for files and directories it doesn't need to write to

To find the user and group your PHP process (web server) run under you could try to run the following PHP script:

if(function_exists('posix_geteuid')){
// use posix to get current uid and gid
$uid = posix_geteuid();
$usr = posix_getpwuid($uid);
$user = $usr['name'];
$gid = posix_getegid();
$grp = posix_getgrgid($gid);
$group = $grp['name'];

}else{
// try to create a file and read it's ids
$tmp = tempnam ('/tmp', 'check');
$uid = fileowner($tmp);
$gid = filegroup($tmp);

// try to run ls on it
$out = `ls -l $tmp`;
$lst = explode(' ',$out);
$user = $lst[2];
$group = $lst[3];
unlink($tmp);

}

echo "Your PHP process seems to run with the UID $uid ($user) and the GID $gid ($group)\n"; ?>

Alternatively, you can use short script with phpinfo(), see section User/Group in output:

phpinfo();

?>

Common Permissions

Here are the most commonly used values for setting permissions on directories and files.

directories	files	result
0700	0600	read/write for owner only. Owner must be the same as the PHP process user.
0770	0660	read/write for owner and group. The PHP process user needs to be in the used group
0777	0666	read/write for everyone. Dangerous everybody with access to the server may write and delete your files. Use only as last resort on trusted machines.

Which permissions to set?

So, how should you set the permissions of the directories mentioned above? In general you should try to set the permissions as restrictive as possible, but there is no general rule which permissions you need to set for your system. On a Linux server with a conventional configuration, however, executing the following commands will do the job:

find -type f -exec chmod 644 {} \;
find -type d -exec chmod 711 {} \;
find pictures upload logs feedcreator -type f -exec chmod 666 {} \;
find pictures upload logs feedcreator -type d -exec chmod 777 {} \;
chmod 755 lang themes gorum/captcha/fonts ecomm/gateways
find themes -name css -type d -exec chmod 755 {} \;

If you have root (super user rights) you can change the owner of files and directories. This means you can change the owner of the Noah's Classifieds files to the web server user (eg. www-data or nobody or apache) and set the permissions to webserver only access. Eg. 0600 for files and 0700 for directories.

If you are a normal user you may be a member of the web server group and can change the files to be owned by this group. Then set the files and directories to be writable by this group. Eg. 0660 for files and 0770 for directories.

If you are alone on the server or running in a completely trusted environment you can simply change the permissions to give everyone access. Eg. 0666 for files and 0777 for directories.

If you're running on a shared web server it is recommended to contact your web server administrator or hosting support and ask for help and recommendations. Point them to this page and they should know what you need to do.

How to set permissions?

On the command line use chmod for changing permissions, chown for changing the owner of files and dirs and chgrp for changing the group. (Note that chown and chgrp may not be available or function as expected if you use a shared web hosting provider.)

When accessing your server through FTP, consult the manual of your FTP tool. Most graphical FTP tools have a dialog to set permissions (often to be found in the right-click context menu).

On some UN*X-like systems, you may be able to use filesystem ACLs to allow the PHP user to write to the files as well. For Sun's ZFS, see the Solaris ZFS Administrator's guide for details. For POSIX-draft compliant filesystems, like Linux ext2/3 or Sun's UFS on Solaris 8 or later, see the man pages for setfacl and getfacl.

Check with your system administrator – some backup systems will ignore ACLs on files. If available, ACLs are more secure than adding the PHP user to your group, giving away the files to the PHP user, or making the files world-writable.

Updating the theme files

Every updates may introduce new features that request some changes in files under the 'themes' folder - in template or CSS files. If you previously changed these files during the Noah's Customization, there is unfortunately no way to automatically update them so that both your and our changes are included! Therefore, the updates simply overwrite these files with our versions. If you want that the customization changes are active again, you must open these files and merge your previous changes into them again. It's important to remember that if you simply overwrite these files with your previously customized ones, it is not a good way, because it will delete our changes and therefore, the program loses functionality! You can update your 'themes' directory after a new release following these steps:

Step 1: If you make an automatic update, the program will list all the files that it will overwrite during the update. Note those files that will be overwritten under the 'themes' directory! If you make a manual update, simply open the update package, browse into its 'themes' directory and keep a record of those files you find there.

Step 2: If you made a customization previously, you probably have a list of files you know that you changed under the 'themes' directory. Note down another small list that contains those files you previously customized and that the update will also overwrite! Make a backup of these files (if you make the automatic update, this will be done by the program automatically)

Step 3: Perform the update

Step 4: In the next step, you are going to make changes in the above noted list of files. Before you do that, however, make a backup copy of them - so that you can restore the layout if your merging of changes happened to contain some errors. That is, make a backup copy of those files that have been just updated by the program under 'themes' in Step 3. (simply duplicate the 'themes' directory into say a 'themes_saved' directory, if it's easier)

Step 5: Install a file comparison tool that makes the following task easier. We recommend the free WinMerge that we also use on a daily routine. Go through the above noted list of files one by one and compare your saved customized version with our updated version. With WinMerge, besides that it visually highlights all the changes between two files, you can also immediately merge your changes into the updated files.

Step 6: Whenever you think you are ready with a file, save it and display a few pages in the program. If you experience some serious destruction, it is probable that during the merge, you have made some error - e.g. you have added some text that makes either the HTML or the CSS invalid. In this case, restore the file from 'themes_saved' and start the merging again. Save the file this time more frequently, so that you can figure out exactly which change of yours cause the destruction and work on it until everything looks ok!

Step 6: Even if you think that you are completely ready, don't delete the 'themes_saved' folder! You can still experience strange layout related things in the future that might be caused by merging. Either you still made a mistake, or your changes and our latest changes may conflict in some ways. Typically, when some page element is not displayed that you think it should be or when elements are misplaced, it is caused by such conflicts. HTML and especially CSS are both fairly complicated techniques - it is not difficult to screw up things in them! Whenever you face with such a layout related bug, the first thing you should try (well before you write a support request!) that you restore all our originally updated files from 'themes_saved' and test the program with them. It's a good practice to keep another directory besides 'themes_saved' that contains your merged versions - say 'themes_mine', so that you can easily “switch” between them by just copying their content into the 'themes' directory!

During the above steps, you have merged your changes into the theme files of the latest version. There is another approach, however, that can be more comfortable if you performed really extensive customization changes in the theme files (or if you don't remember what you actually changed and are afraid of losing those modifications!) It is the opposite of the previous approach: you can merge our changes into your customized theme files.

Note that the above lists detail only the changes in the modern theme. The changes of the classic theme are pretty much analogue, however. Also, they may not contain some of the less important changes - e.g. it's not detailed at all what we modified in the template files of the admin interface - but you probably didn't customized those files anyway.

Configuration

The basic configuration of Noah's Classifieds requires a few easy steps and it starts right after the successful installation. The first page you can see after the installation performs a checking of the configuration and displays the result. It also tells you what to do if it finds any problems. It checks the following:

Because app/config.php might have been created by you manually during the installation, the correctness of this file is checked now - particularly, it is ensured that no white space characters (spaces, new line, etc.) have been accidentally (or automatically by your text editor) inserted before the beginning or after the ending ?> lines. If there would be some, you have to delete them, because white space characters can cause a premature output, which leads to various problems in the program.

The install script creates an admin user with password admin - the configuration page warns you to change this password if you haven't done that yet.

The install script set up the program with an empty System email address. In most of the cases, however, it is required for the program to be able to send out email notifications that the System email address has been set to a valid existing address. The System email address will also populate the 'From' and 'Reply-to' fields of the notification emails.

If the System email address has already been set, the configuration page provides a link through which you can send a test email to the given System email address. If this works and you get the email on that address, you can be pretty sure that the notification sending will work all right in the program. If there are still problems, you may want to use the SMTP method to send out emails.
It is checked whether the GD library is available on your server. This is a Php extension, which is responsible in php programs for the image manipulation. In Noah's Classifieds, it is used for creating thumbnail images to the full sized uploaded pictures. Without this support the program can't generate thumbnails, this way the browser have to shrink every big images 'on-the-fly' on each pages where thumbnails can appear. This method works, but it is far from effective (the page have to download every time every big image!) If GD library is not installed, you should contact your server support to install it.

There are a few directories that the program must have write access to and the configuration script verifies if it can really write these directories.

The configuration script checks whether the “nice URL”-feature is enabled and works in the program. Noah's Classifieds is installed so that it is enabled by default, but it can happen that it still doesn't work, or even if it works, it might cause problems on some unusual server configurations. If it seems so that it doesn't work, the configuration page displays some brief information about its advantages and how to set it up.
There is no need to keep the installation files after installing Noah's - what's more, it can be a serious security leak to have them there in the installation directory. The configuration script checks whether they exist and it warns you to delete them.

From version 2.3.0, most of the php files that used to be directly under the installation directory, must reside under the htaccess-protected app sub directory. The installation root directory may only contain index.php and initdir.php. There is a check that ensures that no spare php files remain under the installation root. Besides the old php files, old update backup directories could also hurt security, so they have to be deleted or moved outside from the web space of your site.

The configuration page is “sticky”, which means it is the default page until you manually disable it by clicking on the link on the bottom of the page! Even if you have already disabled it, you can access it any time as admin by clicking on the Check menu point. It is also highly recommended to make a configuration checking from time to time - especially after updates.

Nice URL feature

Noah's Classifieds supports using nice URLs. This means for example that the link of an ad details page can look like this:

http://your.classifieds.site/item/10

instead of the conventional URL:

http://your.classifieds.site/index.php?item/10

Besides that the former one is nicer, it is also said to be more search engine friendly.

Enabling the Nice URL feature

Rewriting URLs in Apache is done through the mod_rewrite module of Apache 1 or Apache 2. If you click on the Check menu point as admin and the RewriteEngine is not yet enabled, the configuration script attempts to find out whether the rewrite module is available at all. In some cases, this can't be detected for sure (especially if Php is installed as a CGI binary).

The rewrite module is enabled in httpd.conf with the following line (make sure it is not commented out):

LoadModule rewrite_module modules/mod_rewrite.so

If the rewrite module is available, you should have a file under the classifieds installation directory called .htacces with the following content in it, in order to enable nice URLs:

RewriteEngine on
RewriteRule .* - [env=REWRITE_ON:1]
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^(.*)$ index.php?url=$1 [L]

IfModule>

Note that Noah's Classifieds is actually installed with this default .htaccess, so in most of the cases, the nice URL feature must work “out of the box”!

Troubleshooting

Inaccessible pages

If you experience inaccessible, forbidden, or in other ways destructed pages, you should also check the following:

.htaccess override for the classifieds webroot must be enabled. To enable it try adding the following to the httpd.conf:

AllowOverride All
Directory>

FollowSymLinks for the classifieds webroot is enabled. Put the following in .htaccess:

Options +FollowSymlinks
RewriteEngine on

...etc.

If you get Error 400 pages, you can try to add a RewriteBase to the .htaccess file. On the line RewriteBase /noah, you need to replace the /noah with whatever directory you use in your URL to get to the program. Say that your normal URL is http://www.whatever.com/projects/classifieds/index.php . You will need to set the below line to RewriteBase /projects/classifieds.

RewriteEngine on
RewriteBase /noah

If you're running without a RewriteBase, perhaps because you're hosting under a dedicated VirtualHost, and you still get Error 400 pages, try to modify the rewrite rules the following way:

...
RewriteCond %{DOCUMENT_ROOT}%{REQUEST_FILENAME} !-d
RewriteCond %{DOCUMENT_ROOT}%{REQUEST_FILENAME} !-f
RewriteRule ^(.*)$ /index.php?url=$1 [L]
...

mod_rewrite is available, but the program can't detect that it is enabled

There was one more strange case when the mod_rewrite was actually available on a server and usable, but the program still “thought” so that it is not enabled (and therefore generated the conventional URLs). If was caused by that the following line in the .htaccess file - from whatever reason - couldn't pass the information that mod_rewrite is enabled to the program:

RewriteRule .* - [env=REWRITE_ON:1]

We don't know the reason why it happens (probably because this way of setting environment variables is disabled in the global Apache configuration), but if you suspect that this happens, you can use the following workaround: add this line into 'app/config.php: $_SERVER[“REWRITE_ON”]=1; (so the end of the file should look like this):

...
$_SERVER["REWRITE_ON"]=1;
?>

This tells the program that the mod_rewrite is enabled whatever comes from the .htaccess file.

Blank pages

In case of sites where Php is installed as a CGI module, it can happen that you get blank pages. Try to insert the following line into 'app/constants.php' to fix this:

$_SERVER["QUERY_STRING"] = $_SERVER["REDIRECT_SCRIPT_URL"];

Notes

And what if it still doesn't work even you tried everything? Well, at this point, you will probably feel so that those conventional URLs are not so ugly anyway!

The rewrite rules given above will map all non-existing files and directories to the Noah's index.php, this may apply to virtual mappings (aliases), too. Eg. some hosters map web access statistics to a virtual /stats directory. To be able to still access these virtual dirs you need to exclude them in the rewrite conditions. Example:

...

RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_URI} !^/stats/(.*)$
...

CAPTCHA feature

Noah's Classifieds supports using CAPTCHA images in some of the forms. CAPTCHAs are used to prevent automated software from performing actions in Noah's. It is a great way to fight against spammers, but your server must fulfill some requirements so that they can work:

The GD library of Php must be installed (GD is used to generate images),
FreeType support of Php must be enabled, too.

You can check their presence by either asking your server support, or uploading and displaying a 'phpinfo.php' file on your server. (The 'phpinfo.php' file is a simple text file that contains this: If you display it in your browser, it gives you a page with a bunch of information about your system setup. Search for 'GD' and 'FreeType' on that page!). In some cases, it can happen that the CAPTCHA image can't be displayed even if the above libraries are both available. From the 4.0.0 release, you will be able to check the CAPTCHA feature on the 'Check' page of Noah's. If the CAPTCHA image is not properly displayed there, visit this link in your browser:

http://your.classifieds.site/gorum/captcha/captcha.php

If you get either a “Permission denied”, or a “Page doesn't exists” page, at first check that the above 'captcha.php' file surely exists. If that file is really there, but the page is still inaccessible, it means that the permissions are misconfigured on your server. In that case, ask your server support to make it possible to run Php scripts not only in the web root of your site, but also in the sub directories of it! The above link must display nothing but a CAPTCHA image! So, even if it is accessible, but displays some garbage, the feature won't be available for you! (E.g. some hosting services (especially the cheap ones) has been set up so that they prefix every pages of yours with their advertisement banner!)

Making design changes through the admin interface

The customization of Noah's Classifieds has different levels. The most basic level is using the Layout customization section of the Settings form. With this, some quick and easy changes can be performed without any technical knowledge. If you need deeper changes than what can be achieved hare, you must probably edit template and CSS files and refer to the chapters of template customization of the documentation for further help. Every design changes that you can do in the Settings form, you can also achieve with a corresponding template customization, too. This way, the template editing approach seems to “cover” that of the Settings editing, but there are still cases when it is better to chose the latter one even if you are an advanced user! More details later in this chapter.

Usage of the Layout customization fields of the Settings form

Menu Points: You can use this to enable/disable all menu points except the admin specific ones. Unchecking Submit ads has a special meaning, however: it disables the ad submission and hide the menu point only for the normal users and still allows it for admin. This is useful if you want to use the program say like an online shop, where only admin can create advertisements.
'Help' link destination: the full URL of the help file. With this, you can define your own Help page. E.g.: http://yoursite/classifieds_dir/customhelp.html. Note that the Help link that you can see logged in as admin is different from this! Whatever you set here, it only refers to the Help menu point of normal users and non-logged in visitors.
Additional HEAD content: with this, you can insert custom HTML right before the closing HEAD tag of the pages. This is usually a good place to insert additional style sheets, or JavaScript. This is an HTML editor field, but the editor is restricted to adding only JavaScript and CSS content.
Additional BODY content: with this, you can insert custom HTML right after the opening BODY tag of the pages. E.g. you can insert a banner above all the pages here. You may also use this if you want to insert some content (e.g. further banner ads) to the left or right of the classifieds page content. In that case, you can put an opening and the appropriate cell tags here that organize the content, while put the closing tags in the Additional footer content field.
Additional top content: with this, you can insert custom HTML below the header section of the pages (status bar, menus).
Additional bottom content: with this, you can insert custom HTML above the powered footer of the pages.
Additional footer content: with this, you can insert custom HTML right before the closing BODY tag of the pages.

Note that all the HTML editor fields have a Save icon that you can use to save the editor content instantly without submitting the whole form! This is especially handy if you edit more than one HTML editor fields at once and use their Preview icon to check the result. The Preview feature shows the result of your editions just as how the Noah's pages will look like after you save the given change. If you edit one field and save the change with the instant Save button, then edit another field and pop up a preview, the preview page will already contain the effects of the former field, too!

Differences with the template editing approach

- Whatever field you edit in the Settings form, it is a global change! This means it will be applied to all themes. If you use more than one theme and want to realize the same design change with editing templates, you must insert the same modification into the template files of all the themes!
- If you have more themes and the design change slightly differs per theme, you can only realize it with template editing,
- The changes you make in the Settings form will be stored in the database. This means, future program updates can't overwrite them! On contrary, if you edit a template file, you must note that change very well, because the future program updates might overwrite template files, too!

Examples

The Additional HEAD content field is a great tool to override only some of the CSS rules defined in the style sheet files of the themes. E.g. if you add the following to this field, it will align the whole page to the left, position the login menu to the left, too and changes the text color of the status bar to yellow:

If you enter this into the following two fields, you can add a left and right column to the pages:

Additional BODY content:

<table border='1'>

<tr>
<td>Content on the lefttd>
<td>

Additional footer content:

td>

<td>Content on the righttd>
tr>
table>

You can add custom JavaScript effects to the pages using the Additional HEAD content field. E.g. the following will pop up a welcome alert box as soon as a page loads in the browser:

Noah's Classifieds utilizes the highly popular JQuery JavaScript framework to realize cool Web2.0 effects, therefore the core JQuery library is per default included in every pages. This means you can also use the JQuery syntax if you add custom JavaScript content. E.g. a more elegant implementation of the above welcome alert would be the following:

If we already talk about JQuery, we simply can't rest satisfied with such an “economy” welcome alert box. We can utilize the amazingly huge plugin library of JQuery and select one of the several modal box plugins! Let it be for now the one called Impromptu. Download the Impromptu plugin file from their home page and save it under the js directory of the Naoah's installation as jquery.impromptu.js. Then enter the following code into the Additional HEAD content field:

Additional footer content:

td>

<td>Content on the righttd>
tr>
table>

You can add custom JavaScript effects to the pages using the Additional HEAD content field. E.g. the following will pop up a welcome alert box as soon as a page loads in the browser:

Using the template system

Noah's Classifieds is completely template and CSS driven which makes its customization highly flexible.

The directory structure

What makes the design of a program? HTML files that determine the rough structure and content of the pages, CSS files that add the layout, colors, fonts, etc., a bunch of images and some JavaScript that can realize effects on the pages. A set of these elements that implement one design in Noah's is called a theme! Grouping the elements of one theme into a clearly separated directory structure is very important both for you to have a proper overview and for the program itself to be able to switch between themes easily. How does this structure looks like in Noah's:

- themes: this is the root directory that contains every themes. Inside themes, there is a sub directory for each theme which are modern and classic as per the current distribution. Creating a new theme starts with creating its corresponding sub directory under themes. More about this later.
- themes/common_templates: there may be pages that have the same rough structure and content whatever theme one selects. This directory is the place to hold template files that don't depend on any themes. It contains typically the templates of some special admin pages, but can also contain templates of new static pages you create yourself.
- themes//templates: the template files of the given theme. More about what's inside a template file later.
- themes//css: the style sheet files of the given theme. Click here if you want to learn more about CSS in general.
- themes//images: the images files of the given theme.
- themes//javascripts: the JavaScript files used by the given theme. Let's mention here that there are other locations in the Noah's installation you can find JavaScript files. E.g. the js directory right under the installation root contains every JavaScript files that have nothing to do with themes - i.e. which work exactly the same no matter what theme one selects.
- themes//theme_config.php: this is a file, not a directory. It contains some important configuration parameters.

The template files

Let's have a closer look inside a template file! If you are familiar with HTML and open a template file in a text editor, you can see that it is “almost” like HTML file. Why don't we really use regular HTML files and what's that “php” extension than? Well, these things are not so simple, unfortunately! Noah's Classifieds is a dynamic web program which means it inserts the content it computes into the pages on the fly. If you compare the details pages of two ads, you can see that that they look almost the same except the content (the text, the values, pictures, etc.) of the ad. Well, the “except” part is coming from the program and the “almost the same” part is coming from the template! The template has to communicate to the program somehow what content it should inject, exactly where to and when. This is something that a regular HTML file simply couldn't tell! This is why we need template files instead which are themselves small php programs, so that they can communicate with the main program. This may sound threatening, but in fact it is not.

Tools you need

What programs do you need to effectively and comfortably edit themes or create your new theme?

- You will surely need an FTP program to upload files to your server.
- A decent text editor to change the templates and CSS files. One we can really recommend is PSPad. It is free, has syntax highlighting and one can edit files with it directly on the server through FTP!
- If you want to replace or edit the images a theme uses, you probably also need an image editor, too.
- You may be tempted to use a WYSIWYG HTML editor (like Dreamweaver and many others) to change the template files, but don't do! As mentioned above, the template files are not regular HTML files and special HTML editors probably can't handle them properly. They are mostly for creating/editing plain static HTML files, or sites that only consists of static HTML pages.
- If you edit CSS files, you can see that colors are defined with their hexadecimal codes in them. E.g. #ffffff means white. If you want to change the colors of your site, you will find a color picker tool very useful (who knows the hexadecimal color codes by heart anyway?). One free program we can recommend is the Absolute Color Picker.

How to create a new theme

You have two choices. If you don't want to keep any of the current two themes of Noah's, you can select one of them that is closer to your goal and start changing it until the site looks like you want. The other approach is to keep the current themes intact and create a new one that you will furthermore work on. The easiest way to create a new theme is to choose one of the existing ones and make a copy of it under themes. E.g. take the modern theme and copy its directory (with all its content!) into my_theme (this way my_theme will be a third sub directory under themes). Now, if you log in as admin and open the Settings form, you will see that a new theme called My theme will appear in the Default theme and in the Allowed themes to select from fields. Add My theme to the Allowed themes to select from list and you may also select it as the Default theme. With this, you have created a new theme that is ready to use! Make sure you select it from the Theme selector drop-down list to make it the active theme!

Changing a theme

Whether you create a new theme as described above, or change an existing one, you will get to the point where you must edit it. This is a quick start guide about how to do it which we present now in a FAQ style. We try to go from the simplest operations to the more complicated ones. Every time you need a deeper look, just follow the links for more details. Note that we use the modern theme as an example - the steps would be slightly different in the classic theme.

Q1 - I want to display my own logo instead of Noah's.

A: This is one of the first things you will probably want to do and in one also the simplest and might even be the only thing that you do to customize your installation! It is really simple. You can find the logo under the images directory of the theme. It's called headpic.gif. Create your own logo, name it to headpic.gif and upload it into the images directory replacing the original logo.

Q2 - What if the new logo is say just a jpg file? I can't upload it as a gif than!

A: In that case, you must make a small edit in the main template file which is the layout.tpl.php under the templates sub directory of the theme. Simply search for the string headpic.gif in it and replace it with whatever name you call the new logo file!

Q3 - How can I change the main logo, so that it is a link to the home page?

A: Again, this is an easy edit in layout.tpl.php. Simply search for the IMG tag that displays the logo (headpic.gif):

<img src='imagesDir ?>/headpic.gif'>

and replace it with the following:

<a href='URL_of_your_classifieds_installation'><img src='imagesDir ?>/headpic.gif'>a >

Q4 - What if the new logo looks bad on the grayish faded background of the header?

A: You must replace that background image in that case. It is called top_shadow.jpg. The procedure is the same as in Q1.

Q5 - I would rather give a plain color background to the header!

A: The background of the header is defined in the layout.css file:

#top {
background:transparent url(../images/top_shadow.jpg) no-repeat scroll left center;
height:108px;
text-align:left;

}

Change the background property this way (this turns the background of the header into plain white:

background: #ffffff;

Note that you can also easily change the height of the header in the #top selector!

Summary: layout.tpl.php is the main template file of the program - it specifies the Noah's “frame” that appears around every pages, which is the the header section, the status bar, the menus and the “powered by” footer. layout.css is the style sheet file that belongs to it.

Q6 - What template file should I edit if I want to change the menus?

A: The menu bars have their own template files: the top most menu is defined in menu_login.tpl.php. Once a normal user logs in, the user menu will be displayed and it is defined in menu_user.tpl.php. If you log in as admin, you will see the menu bars specified by menu_admin.tpl.php and menu_category.tpl.php.

Q7 - How can I change the order of the menu points?

A: Open the corresponding menu template file in a text editor. You will see that each menu item has a given section of HTML markup there. You will easily identify such a section based on the “pattern” of the whole file. E.g. the sections in the menu_login.tpl.php look like this:

if( !empty ($this->loginMenu["home"])): ?>

echo $this->loginMenu["home"]["link"] ?>">

echo $this->loginMenu["home"]["label"] ?>

endif; ?>

This was the section of the Home menu point. Changing the order of the menu points can be achieved by simply moving their section to an other location in the file!

Q8 - How can I remove certain menu points?

A: Well, the easiest way to disable a menu point is to do it in the Settings form as described here . If you still want to do it with editing the templates, you can do it simply by deleting the section of the menu point from the template file. Note that deleting any elements from the pages is as simply as deleting the section that specifies the element from a template file where it is located! E.g. You can hide the Help menu point from the normal user by deleting the following section from menu_user.tpl.php:

if( !empty ($this->userMenu["help"])): ?>

· echo $this->userMenu["help"]["link"] ?>">

echo $this->userMenu["help"]["label"] ?>

endif; ?>

Q9 - How can add my own menu points?

A: Basically, you should open the template file that belongs to the manu bar you want to insert your menu point, find the place in it where you want to insert it exactly and add a new section that describes your menu point! E.g. you can add your custom menu point to the login menu by inserting the following section into menu_login.tpl.php:

<td ><div class='loginMenu'><a href='url_of_the_menu_point'>
Custom menu pointa >

div >td >

You can add a custom menu point to the user menu by inserting the following section into menu_user.tpl.php:

<li ><a href='url_of_the_menu_point'>
Custom menu pointa >

li >

Summary: You can change the position of elements on the interface by changing the position of the section that describes them in the template file that contains them. You can delete elements from the interface by deleting their section from the template file. You can add new elements to the interface by adding a section that specifies them to the template file that describes the area where you want to add the new element. You can change how an element looks like by changing the content of the style sheet selector that describes the design of that element in the corresponding CSS file. Some hints and warnings:

- We are talking about HTML and CSS editing here. Even if you can perform most of these changes without a deep web-designer knowledge using only some common sense, keep in mind that both HTML and CSS have quite a strict syntax and rules that you should not break with your changes. We encourage you to edit the themes bravely, but after every change, preview the result in the browser. If you find the result unsatisfying, use the undo feature of your editor to restore the original state and experiment with a new change! It's always wise to save a backup copy of the edited files, too!
- Do you use Internet Explorer? Keep in mind that many of the visitors of your site will use other browsers and however you change a theme, the result must look properly in all the major browsers! You can even consider different screen resolutions. If you don't want to install many versions of many browsers, you can test how your site looks like in any of them using this online service .
- Don't carry this too far, however. We really don't want to encourage you to be sloppy, but we wouldn't worry too much if our site had little faults when viewed with say the Kazehakaze browser on Ubuntu Linux (sorry if you are just a Kazehakaze/Ubuntu fan)!

Q10 - I want to have more or less category columns instead of four.

A: Open the theme_config.php file in the text editor and change the number in this line:

$categoryColumnsNum=4;

Q11 - I have changed the number of category columns. How can I change now the width of the category panels, so that they just fit?

A: The categories are organized in an HTML table. It's rows and column are computed based on the requested number of columns and the total number of categories to display. It is also considered whether a category has a picture and description (the title is the only mandatory field of a category!). The structure of the category table is created by the category_list.tpl.php file. If you want structural changes, this is the file you must edit. The design of the category panels on the other hand is defined in the category.css file. It is optimized for a fixed category panel width and for having four different color representations. If you want to change the width or the colors, you need to create new background images, too, for the top and bottom part of the category panel. Of course you can decide so that you replace this design with a simpler one that say doesn't use pictures as a background. You will probably need somewhat deeper CSS knowledge to achieve such changes.

Hint: If you want a better visual overview about the structure of the category table and about which CSS properties specify the appearance of which elements, there is an invaluable tool you can use. It's a FireFox plugin called FireBug (of course you must have a FireFox browser installed to use it!). Amongst many others, it has an Inspect feature - if you activate it and move the mouse over any element on the page, it displays which HTML tag draws that element and which CSS rules are applied to it (and in which files/lines you can exactly find those rules). You can even change the HTML and CSS in FireBug directly and immediately see the effects of the changes!

Q12 - How can I change the style of the lists, forms and details pages of the program?

A: You can do that by editing the pages.css file. If your changes need alterations in the HTML structure, too, you have to edit the default_list.tpl.php, default_deleteform.tpl.php, default_form.tpl.php and default_details.tpl.php files.

Q13 - How can I change the style of the ad details pages?

A: You can do that by editing the pages.css file. If your changes need alterations in the HTML structure, too, you have to edit the item_details.tpl.php and item_details_sidebar.tpl.php files.

The template files

Overview

The template language

In order to communicate the “what”, “where” and “when” factor, templates use some special “template language” syntax in general. In case of Noah's Classifieds, the chosen template language is Php itself. (For those who are interested in more details, the template framework we use is called Savant2.) If you open a template file in a text editor, you can see that it contains two kind of texts: plain and regular HTML and Php code blocks surrounded by the following delimiters: and ?>. The HTML and Php content are sometimes mixed even inside one line! The details of the template syntax is the following:

Inserting content:

// Use the echo command to insert dynamic content into a page:
echo $variableName ?>

// E.g.: the following inserts the text of the status bar into the

of the status bar:

echo $this->userStatus ?>

// You could write it inline this way, too:

echo $this->userStatus ?>

Conditional insertion:

if( condition ): ?>
// Whatever you write here, it will be displayed on the page only if condition is true

endif; ?>

// More conditions:
if( condition1 ): ?>

// Displayed on the page only if condition1 is true
if( condition2 ): ?>
// Displayed on the page only if condition1 is true
else: ?>

// Displayed on the page if neither condition1 nor condition2 is true
endif; ?>

// E.g.: the following displays the language selector only if it is enabled at all:
if( $this->languageSelector): ?>

echo $this->languageSelector ?>

endif; ?>

Loops (repetitive insertion):

for($i=0; $i<10; $i++): ?>

// This will be displayed on the page 10 times
endfor; ?>

foreach($list as $listElement): ?>

// This will be displayed on the page for every element of a list
endforeach; ?>

// E.g.: the following displays every categories one by one:
for( $i=0; $i<$catNum; $i++ ): ?>

// Displaying one category
endfor; ?>

// The following displays every custom fields that is placed in the top area of the side bar of the ad details panel:
foreach( $this->sideBarContent["top"] as $value ): ?>

echo $value ?>

endforeach; ?>

Including another template file:

The template files can include other template files. With this possibility, you can achieve a better structure and overview amongst the template files. E.g. the content of the menus has been laid out into separate template files which are included by the central layout.tpl.php.

include $this->loadTemplate("other_template_file.tpl.php"); ?>

The program looks for the include file in the templates directory of the theme first, and if it doesn't find there, in the common_templates.

Inserting content on certain pages only:

This is a special case of the Conditional insertion section above you can insert page-dependent content with! Use the currentPageIs function to query the URL of the displayed page. (Note that one template file can belong to many pages! E.g.: the layout.tpl.php files serves the frame for every pages of the program, the category_list.tpl.php serves the content area for every pages where categories are displayed, the item_details.tpl.php serves the content area for every pages where an ad details page is displayed, etc.)

// E.g. The following displays a Welcome message if the current page is just the start page of the program:
if( $this->currentPageIs("/") ): ?>

Welcome dear users!
endif; ?>

// The '*' wildcard can be used, too. The following displays a general message on every ad details page and a special message on the ad details page with ID 5:
if( $this->currentPageIs("item/5")): ?>

This item is the best bargain!
elseif( $this->currentPageIs("item/*")): ?>

General text for every other ad
endif; ?>

Template variable reference

layout.tpl.php

Title	Description	Possible values or example	Insertion example
Language	Contains the two-letter language specifier of the currently selected language	'en', 'es', 'hu', 'de, …	language ?>
Reading direction	Tells if the selected language is read left to right or right to left	'ltr', 'rtl'	langDir?>
Base URL	Base URL and path of the installation	E.g.: 'http://mysite.com/classifieds'
Title prefix	The 'Title prefix' field of the Settings form	E.g.: '[Noah's Classifieds] -'	titlePrefix ?>title ) echo ' - '.$this->title; ?>
Page title	The title text of the page	E.g.: 'Advertisement categories'	titlePrefix ?>title ) echo ' - '.$this->title; ?>
Page description	The description text of the page	Arbitrary text
Page keywords	The keywords of the page	Arbitrary text
CSS directory	The theme directory that contains the CSS files	E.g.: 'themes/modern/css'
Noah release number	Noah release number	E.g.: '2.4.1'
External JavaScript	HTML to include the JavaScript files	...	jsIncludes ?>
Internal JavaScript	HTML to include JavaScript code		javaScript ?>
Additional HEAD content	Inserts the 'Additional HEAD content' from the Settings form	Whatever you enter in the 'Additional HEAD content' field. Typically, JavaScript and CSS include/code.	extraHead ?>
Additional BODY content	Inserts the 'Additional BODY content' from the Settings form	Whatever you enter in the 'Additional BODY content' field. Typically, JavaScript and CSS include/code.	extraBody ?>
Images directory	Path to the 'images' directory of the theme	E.g.: './themes/modern/images'
RSS	Inserts the RSS feed links	array 0 => 'link' => string 'rss/latest/20' 'label' => string 'Latest 20 ads' 'linkClass' => string 'color1' 1 => array 'link' => string 'rss/latest/20/category/1' 'label' => string 'Latest 20 ads in this category' 'linkClass' => string 'color2'	rssFeed as $item ): ?> o " href="/">
User status	Status text that informs about whether a user is logged in and who the user is	E.g.: 'You are logged in as admin.'	userStatus ?>
Language selector	The language drop-down list of the multi-language feature		languageSelector): ?> languageSelector ?>
Theme selector	The theme drop-down list		themeSelector): ?> themeSelector ?>
Additional top content	Inserts the 'Additional top content' from the Settings form	Whatever you enter in the 'Additional top content' field.	extraTopContent ?>
Info text	Messages from the program	E.g.: 'You have mistyped your password!'	infoText): ?> infoText ?>
Navigation bar	Shows the location of the object in the category hierarchy	Home » Cars » Economy cars	navBar): ?> navBar ?>
Page content	The main dynamic page content: lists, forms, details pages, etc. The program utilize other template files to create it.		display() ?>
Additional bottom content	Inserts the 'Additional bottom content' from the Settings form	Whatever you enter in the 'Additional bottom content' field.	extraBottomContent ?>
Version footer	Inserts the 'Version footer' from the Settings form	Powered by Noah's Classifieds 2.4.1 - try Noah's Classifieds V8 e-commerce enabled	versionFooter ?>

The menu templates

Noah's Classifieds has four separate menu bars. The topmost, that is always visible, is called login menu and its template file is menu_login.tpl.php. If a normal user logs in, the user menu will be displayed (menu_user.tpl.php). If you log in as an admin, there are two menu bars: the admin menu and the category menu (menu_admin.tpl.php and menu_category.tpl.php). All of these template files are included by the layout.tpl.php when necessary. Evry menu template file gets the menu in an array of menu points from the program, where each menu point is composed of a link and a label.

...

Title	Description	Possible values or example	Insertion example
Login menu	Contains the points of the login menu	array 'logout' => array 'link' => string 'user/logout/' 'label' => string 'Logout' 'addAd' => array 'link' => string 'item/create_form/' 'label' => string 'Submit ad' ...	loginMenu["home"])): ?>	"> loginMenu["home"]["label"] ?>
User menu	Contains the points of the user menu	array 'myProfile' => array 'link' => string 'user/modify_form/' (length=17) 'label' => string 'My profile' (length=10) 'myAds' => array 'link' => string 'item_my/list/' 'label' => string 'My ads' ...	userMenu["myProfile"])): ?> · "> userMenu["myProfile"]["label"] ?> ...
Admin menu	Contains the points of the admin menu	array 'myProfile' => array 'link' => string 'user/modify_form/' 'label' => string 'My profile' 'settings' => array 'link' => string 'settings/modify_form/1' 'label' => string 'Settings' ...	adminMenu["myProfile"])): ?> · "> adminMenu["myProfile"]["label"] ?> ...
Category menu	Contains the points of the category menu	array 'addCategory' => array 'link' => string 'cat/create_form/' 'label' => string 'Create New Category' 'organizeCategory' => array 'link' => string 'cat/organize_form/' 'label' => string 'Organize categories' ...	categoryMenu["organizeCategory"])): ?> · "> categoryMenu["organizeCategory"]["label"] ?> ...

category_list.tpl.php

The list of categories is passed to the category_list.tpl.php template by the program in an array of categories. In that array, every item has a link, title, ad count, picture and description where the latter two can be empty. This array is rendered by the template file into an HTML table. The template file begins with the definition of some helper variables it uses to establish the rows and cells.

Title

Description

Possible values or example

Insertion example

Table width

The width of the HTML table.

'100%'

Categories	The list of categories	array 0 => object 'link' => string 'list/1' 'title' => string 'Cars' 'description' => string 'A lot of cars, different classes, little and large ones, different manufacturers, you can check for the price as well...' 'itemNum' => string '5' 'picture' => string './pictures/cats/1.jpg' 1 => object 'link' => string 'list/2' 'title' => string 'Hardware' 'description' => string 'Find hardware into your computer, from memory to CD-Rom, from hard disk to monitor, whatever you want...' 'itemNum' => string '3' 'picture' => string './pictures/cats/2.jpg' ...	title ?> [itemNum ?>]
Number of categories	Number of categories	'4'	...
Number of columns	Number of category columns.	'4'
Category width	The width of one category cell in percent.	'25'
Number of colors	The number of different alternating category cell colors	'4'

Category related template variables

The 4.0.0 version of Noah's has more possibilities to display or use category related information in the template files. This page goes into the details of what these variables exactly contain and how you can use them in your theme customization. If you want to inspect the values of these variables in your installation, you can always use the Template debug mode option in the Settings form.

'categories'

This is the good old template variable you could always use to access the the list of categories on the category listing pages. E.g. it contains the list of main categories on the http://yoursite.com page of the list of sub categories of the category with ID 1 on the http://yoursite.com/list/1 page. The simple classic category browsing style of Noah's, in which always one level of categories are visible, can be easily achieved with this. This is an example of how the content of this variable looks like in its simplest form:

There is another common style of category browsing, however, where the list of direct sub categories of a main category are displayed right under the main category! This way, the users can see two levels from the category hierarchy at once. You can add this second level of categories to the categories variable using the $populateTwoLevelsOfSubCategories variable in the theme_config.php file (see themes/modern/theme_config.php for more details). If you set the $populateTwoLevelsOfSubCategories to TRUE, the content of the categories variable will look like the following:

'currentCategory'

This variable contains the “category context” while a user is browsing on the site. E.g. the variable will contain the the details of the Cars category if you browse into the listing of Cars, or if you display the details page of a 'Cars' ad. This variable behaves “sticky” - i.e. it remains set to Cars until you visit an other page that puts you in the context of an other category. E.g. if you are in the 'Cars' context and you display say the 'Recent ads' list (which is a category-context independent one), you remain furthermore in the 'Cars' context. The value of currentCategory is 0 until you enters in a category context the first time.

Note that the currentCategory “understands” the $populateTwoLevelsOfSubCategories variable, too: if it's set to TRUE, the currentCategory will contain the direct sub categories of the current category, too. E.g.:

The following is a primitive example of using the currentCategory variable in the layout.tpl.php file. If someone is in the Dating > Men category, it displays a blue background and when one is in the Dating > Women, it displays a pink background:

if( $this->currentCategory==0 ): ?>

elseif( $this->currentCategory->name=='Man' ): ?>

elseif( $this->currentCategory->name=='Woman' ): ?>

else: ?>

endif; ?>

'fullCategoryTree'

There are further, more advanced category browsing styles which needs that you can access the full category hierarchy of the site on every pages. Examples:

- A category “quick jump” tool: a selection list of all the categories one can use to browse into an other category from any page,
- An expandable-collapsible category navigator tool or category menu that may completely replace the conventional simple category browsing style supported by the categories variable.

Note that passing the full category tree over to every pages may easily be a performance issue if you have a large number of categories! Therefore, this feature is per default disabled. You can enable and configure it using the following variables in the theme_config.php file:

$populateFullCategoryTree = FALSE;

Set it to TRUE, in order to enable the feature!

$categoryTreeFormat = "single_array"; // other possible values: "multi_array", "html"

You have three choices to control the format of this variable: single_array, multi_array and html. The following is an example of the output when you set this variable to single_array. The categories are passed over in a one dimensional array where the depth property contains level of the category in the hierarchy. This format is ideal to construct a category quick jump list from:

If you set $categoryTreeFormat to multi_array, the categories will be put into the fullCategoryTree variable in a multi dimensional array. Example:

Most of the JavaScript/DHTML tools you can use to construct an expandable-collapsible category navigation operate on or require an HTML

o list of the categories, you can use the html option of the $categoryTreeFormat variable. It provides the following format in its simplest form:

<ul>
<li>
Cars
<ul>
<li>
Economy cars
li>

<li>
Pickups
li>
ul>
li>
<li>

Hardware
<ul>
<li>
Hard disks
li>
<li>
Memory chips
li>

ul>
li>
<li>
Cottages
li>
<li>

Dating
<ul>
<li>
Men
li>
<li>
Women
li>

ul>
li>
ul>

If you set $categoryTreeFormat to html, you have the following further options to configure the content of the fullCategoryTree variable:

// other possible values are "ol", "div" if you want to use an

list instead of

$categoryTreeMainTag = "ul";

// you can give a CSS class to the main

)
$categoryTreeMainClass = "";

// you can give a CSS class to the node of the currentCategory, in order to distinguish the
// the active "category context" from all the other categories:
$categoryTreeActiveNodeClass = "";

// instead of the simple category names, you can use links to the categories by setting the following to TRUE:
$categoryTreeWithLinks = FALSE;

(or

The following is an example of the output when you use these settings:

$categoryTreeMainTag = "ol";
$categoryTreeMainClass = "collapsibleTree";
$categoryTreeActiveNodeClass = "active";

$categoryTreeWithLinks = TRUE;

<ol class='collapsibleTree'>
<li class='active'>

<a href='cars'>Carsa>
<ol>
<li>
<a href='cars/economy_cars'>Economy carsa>

li>
<li>
<a href='cars/pickups'>Pickupsa>

li>
ol>
li>
<li>
<a href='hardware'>Hardwarea>

<ol>
<li>
<a href='hardware/hard_disks'>Hard disksa>
li>

<li>
<a href='hardware/memory_chips'>Memory chipsa>
li>

ol>
li>
<li>
<a href='cottages'>Cottagesa>

li>
<li>
<a href='dating'>Datinga>

<ol>
<li>
<a href='dating/men'>Mena>
li>

<li>
<a href='dating/women'>Womena>
li>

ol>
li>
ol>

list hierarchy of the categories. They use then CSS to “decorate” this list and they use JavaScript to assign the necessary “expand” and “collapse” actions to its nodes. To support these widgets with a “ready to go”

Internationalization

From the 2.2.0 version of Noah, it is possible to use the multi-language feature. The 2.2.0 release contains a couple of languages for start, but the language files we use are mostly inherited from the old 1.3 version of Noah. Because the program has changed a lot since the 1.3, these old translations don't cover the 100% of all the current interface texts. Any contributions to extend or correct the existing translations, or create new ones are welcome!

Enabling the multi-language feature

The Settings form contains a new section called “Language properties”. It has three fields:

- Default language: this is English by default, but you can select any other from the currently available languages,
- Allow others to change language: if this is enabled, a selection drop down will be displayed on the pages that allows the immediate change of the program language for all the users,
- Allowed languages to select from: setting the previous field only makes sense if you select here at least two languages
- Language direction: if you have the simple case when all the languages you want to use are either “left to right”, or all of them are “right to left”, you can set this property here.

If you have enabled the feature, the language selector drop-down list will appear next to the theme selector. If a user changes the language, his or her selection will be stored in a cookie and this way, the program will “remember” that permanently.

The scope of the multi-language feature

What texts are actually affected when the feature is used:

- Basically, all the interface texts: i.e. all the texts coming “from the program” (the texts which can be found in the language files),
- The texts of some of the notification emails may also be affected (although, none of them are actually translated yet). E.g. if a German translation of the email_to_friend.html notification template file existed and someone switched to German and then used the “send to a friend” feature of an ad, the German version of the email would be sent to the friend.
- Even the template files can be internationalized (details are below)

The texts that are not affected by the feature:

- Nothing that is coming from the database (i.e. none of the texts that either admin or any other users entered in any forms). E.g. the category names and descriptions, ad titles and descriptions, names of the ad fields, etc. will not change their language when one switches to another language with the selector tool.

In the 3.1.0 release, however, we have added a workaround that still makes it possible to internationalize the part of the database content that is set up by the administrator! E.g. category names and descriptions, custom field names, explanation texts, etc. Details are below.

Adding a new language to the program

You can add a new language to the program by creating new language files (or you can extend or correct the currently available languages by editing the current language files). All the language files can be found under the lang sub directory (and under the ecomm/lang sub directory in case of the EComm edition!) and every languages has two language files. E.g. you can find all the English texts in the lang_en.php and lang_admin_en.php files. The lang_admin_xx.php files contain texts that only appear on the admin interface. This separation aims to support the translators with providing the minimum set of texts in the separate lang_xx.php files that they must anyway translate to create a usable language version! As opposed to this, the lang_admin_xx.php files contain much more “advanced” texts, but these texts need not necessarily be translated, since they will be only ever seen by admin. (However, we would be glad if you translated them, too and we could provide full language support to the admin interface, as well!)

The process of creating a new translation is the following:

- Create a copy of lang_en.php and lang_admin_en.php under the lang directory (and under the ecomm/lang sub directory in case of the EComm edition). Name the copies with the language code of the translation you are about to make. Use standard two letter codes, please. E.g. for an Esperanto translation, create lang_eo.php and lang_admin_eo.php.
- Open the newly created language files in a text editor and translate them. A language item in the files looks like the following and the text you must translate is the one between the second pair of quotation marks:

$lll["categories"]="Categories";

- You will find a block near the top of the lang_xx.php files where all the current languages are listed. Add there a new line with your newly created language. E.g.:

$lll["defaultLanguage_eo"]=$lll["allowedLanguages_eo"]="Esperanto";

(if you forget this, only the language code of your new translation will appear in the language selector drop-down lists)

The program will automatically detect that you created new language files and the new language will appear in the Settings form both in the Default language and in the Allowed languages to select from fields. Extend the Allowed languages to select from list with the new one to make it appear in the language selector. You can also establish translations of notification emails, too, by creating copies of the notification template files! You can find the notification templates under notifications. E.g. to create the Esperanto version of the email_to_friend.html template, make a copy of it into email_to_friend_eo.html and translate it!

Some important notes:

- Noah's Classifieds uses the UTF-8 character set to save and display special characters found in many languages. If you make a translation of a file into a language that has special characters, save the language file with the UTF-8 character set! Most text editors support this - even Notepad does. Also, if you open an existing language file that contains spacial characters, open it as a UTF-8 file (or specify after the file open that your editor should treat it as UTF-8), so that your text editor can properly display all the characters.
- If your language file contains a language that has an other reading direction than what you set in the 'Language direction' property of the Settings form, you can overrule that property in the language file itself. E.g. to tell that a language has “right to left” direction, insert the following line into one of the language files:

$langDir="rtl";

Translating the template files

From the 3.1.0 version, it is possible to internationalize the template files, too. You have two choices here and the decision mainly depends on the amount of language texts in the given template file:

1. If a template file contains only a few language texts (the rest of the file is mostly just HTML), it makes sense that you do the translation “inline”

If you have a sentence in the template file say “Our customer support is very friendly”, replace it with the following Php code:

echo $this->addLangText("friendlySupport") ?>

Then insert the following into one of the language files - e.g. if you want that the sentence is displayed in German than into 'lang_de.php':

$lll["friendlySupport"]="However you translate it into German.";

2. If a template file contains long language texts and fewer HTML, you can make different language versions from the template file

E.g. if you have a template file called 'faq.tpl.php' that contains the FAQ text in your default language, but you want to maintain a German version of the FAQ page, too, create a file called 'faq_de.tpl.php' in the same template directory. Translate its content and it will be chosen by the program automatically as the template of the FAQ page when one views the page in German.

Translating the database content

From 3.1.0, it is possible to translate even some of the texts that has been written into the database. This only includes the texts that the administrator can set up in the program - e.g. the categories, custom fields, settings, notifications and custom lists. So that this works, you must create a third language file called 'lang_custom_xx.php' in the 'lang' directory (where 'xx' replaces the country code of the language). The content of this new language file will be analogue to the two old language files. For an example, see the 'lang_custom_hu.php.example' file in the latest update!

// You can use a file like this to provide translations of texts that are stored in the database.

// Categories:
// e.g. $lll[1]["category"]["name"] identifies the 'Name' field of the category object with ID 1.
$lll[1]["category"]["name"]="Autók";

$lll[1]["category"]["description"]="Egy csomó külonbozõ típusú autó";
$lll[1]["category"]["customAdListTitle"]="Sajat egyedi cim";

$lll[2]["category"]["name"]="Hardver";
$lll[2]["category"]["description"]="Itt alkatrészeket találhat számítógépébe";

$lll[2]["category"]["customItemListTitle"]="";

// ...

// Custom fields:
// e.g. $lll[1]["field"]["name"] identifies the 'Name' property of the custom field object with ID 1.
$lll[45]["customfield"]["name"]="Fogyasztas";

$lll[45]["customfield"]["expl"]="Magyarázó szöveg"; // the 'Explanation text' property
$lll[45]["customfield"]["default_text"]="ketto"; // the 'Default' property of the Text and Selection fields

$lll[45]["customfield"]["default_multiple"]="ketto"; // the 'Default' property of the Multiple selection and Checkbox fields
$lll[45]["customfield"]["formatPrefix"]="prefiksz"; // the 'Prefix' property

$lll[45]["customfield"]["formatPostfix"]="posztfiksz"; // the 'Postfix' property
$lll[45]["customfield"]["precisionSeparator"]="prec"; // the 'Precision separator' property

$lll[45]["customfield"]["thousandsSeparator"]="thou"; // the 'Thousands separator' property
$lll[45]["customfield"]["format"]="format %s"; // the 'Display format' property

$lll[187]["customfield"]["name"]="Promocios szint";
$lll[187]["customfield"]["values"]="semmi, arany, ezust, bronz"; // the 'Possible values' property

$lll[186]["customfield"]["name"]="Promocios szint";
$lll[186]["customfield"]["values"]="semmi, arany, ezust, bronz"; // the 'Possible values' property

// ...

// Custom lists
// e.g. $lll[1]["customlist"]["listTitle"] identifies the 'Title' property of the custom list object with ID 1.
$lll[1]["search"]["listDescription"]="Hirdeteseim"; // the 'Description' property

$lll[1]["search"]["listTitle"]="Hirdeteseim";
$lll[2]["search"]["listDescription"]="A 100 legfrissebb hirdetes"; // the 'Description' property

$lll[2]["search"]["listTitle"]="Legfrissebb";
$lll[3]["search"]["listDescription"]="A 100 legnezettebb hirdetes";// the 'Description' property

$lll[3]["search"]["listTitle"]="Nepszeruk";

// ...

// Settings
// e.g. $lll[1]["settings"]["titlePrefix"] identifies the 'Title prefix' property of the settings object.
$lll[1]["settings"]["titlePrefix"]="Magyar cim - ";

$lll[1]["settings"]["mainTitle"]="Cim"; // the 'Title tag' property
$lll[1]["settings"]["mainDescription"]="Leiras"; // the 'Description meta tag' property

$lll[1]["settings"]["mainKeyword"]="kulcsszo1, kulcsszo2"; // the 'Keywords meta tag' property
$lll[1]["settings"]["dateFormat"]="m-d-Y"; // the 'Date format' property

// Notifications
// e.g. $lll[1]["notification"]["title"] identifies the 'Title' property of the notification object with ID 1.
$lll[1]["notification"]["title"]="Regisztracios email";

$lll[1]["notification"]["subject"]="Regisztracios email"; // the 'Subject' property
$lll[1]["notification"]["body"]="Magyar nyelvu email szoveg"; // the 'Body' property

?>

Some notes on this:

- The above extracts mentions ID-s of objects. You can easily figure out the ID of an object by displaying either the details page or the modify form of it and then looking into the location bar. E.g. 'field/modify_form/9' is the modify form of custom field with ID 9.
- If you have special characters in your language file, don't forget to save the 'lang_custom_xx.php' file in UTF-8!
- Tip: the 'lang_custom_xx.php' files will not be overwritten during the program updates. So, if you perform the internationalization of template files and you need to insert therefore new language texts into a language file (see the previous section). E.g.:

$lll["friendlySupport"]="However you translate it into German.";

It makes sense that you put them just into the 'lang_custom_xx.php'! You don't have to care about merging your additions again into the language file after every updates.

Creating new pages

Noah's Classifieds has some basic content management possibilities that make it possible to create new static pages. These pages have then the same “surrounding” as all the built in Noah's pages and new menu points can be added, too, that point to these pages, so that users can access them. To demonstrate this, the install package actually already contains a small example FAQ page that you can access through this link: http://yoursite.com/yourclassifieds/faq. (Don't expect a real FAQ page - it is just a demo of the concept itself!). The template file which describes the content of this faq page is the following: 'themes/common_templates/faq.tpl.php'.

So, what you need to do to create say a 'terms and conditions' page that you can access under http://yoursite.com/yourclassifieds/terms ? Just create a file called 'terms.tpl.php' under 'themes/common_templates' and fill it with your custom text. You can put HTML in it, but note that it should be only a partial HTML file, not a full one (a proper full HTML file has a HEAD section and BODY section. However, because this template only represents a text that you intend to insert into a page having already its own full HTML structure itself, you can’t insert an other full HTML document into that. It would invalidate the whole HTML page!).

If you allow the switching between different themes and want to create differently designed terms pages for each theme, then you must place the template files under the 'templates' directories of the themes themselves instead of the 'common_templates' directory (e.g. 'themes/modern/templates')

If you already have the page, you can add a new menu point to it. As a Reminder from the (Changing the Theme Documentation)See the Below to read more about manipulating the menus!

Tools you need

What programs do you need to effectively and comfortably edit themes or create your new theme?

- You will surely need an FTP program to upload files to your server.
- A decent text editor to change the templates and CSS files. One we can really recommend is PSPad. It is free, has syntax highlighting and one can edit files with it directly on the server through FTP!
- If you want to replace or edit the images a theme uses, you probably also need an image editor, too.
- You may be tempted to use a WYSIWYG HTML editor (like Dreamweaver and many others) to change the template files, but don't do! As mentioned above, the template files are not regular HTML files and special HTML editors probably can't handle them properly. They are mostly for creating/editing plain static HTML files, or sites that only consists of static HTML pages.
- If you edit CSS files, you can see that colors are defined with their hexadecimal codes in them. E.g. #ffffff means white. If you want to change the colors of your site, you will find a color picker tool very useful (who knows the hexadecimal color codes by heart anyway?). One free program we can recommend is the Absolute Color Picker.

How to create a new theme

Changing a theme

Q1 - I want to display my own logo instead of Noah's.

Q2 - What if the new logo is say just a jpg file? I can't upload it as a gif than!

Q3 - How can I change the main logo, so that it is a link to the home page?

A: Again, this is an easy edit in layout.tpl.php. Simply search for the IMG tag that displays the logo (headpic.gif):

<img src='imagesDir ?>/headpic.gif'>

and replace it with the following:

<a href='URL_of_your_classifieds_installation'><img src='imagesDir ?>/headpic.gif'>a>

Q4 - What if the new logo looks bad on the grayish faded background of the header?

A: You must replace that background image in that case. It is called top_shadow.jpg. The procedure is the same as in Q1.

Q5 - I would rather give a plain color background to the header!

A: The background of the header is defined in the layout.css file:

#top {
background:transparent url(../images/top_shadow.jpg) no-repeat scroll left center;
height:108px;
text-align:left;

}

Change the background property this way (this turns the background of the header into plain white:

background: #ffffff;

Note that you can also easily change the height of the header in the #top selector!

Q6 - What template file should I edit if I want to change the menus?

Q7 - How can I change the order of the menu points?

if( !empty($this->loginMenu["home"])): ?>

echo $this->loginMenu["home"]["link"] ?>">

echo $this->loginMenu["home"]["label"] ?>

endif; ?>

This was the section of the Home menu point. Changing the order of the menu points can be achieved by simply moving their section to an other location in the file!

Q8 - How can I remove certain menu points?

A: Well, the easiest way to disable a menu point is to do it in the Settings form as described here. If you still want to do it with editing the templates, you can do it simply by deleting the section of the menu point from the template file. Note that deleting any elements from the pages is as simply as deleting the section that specifies the element from a template file where it is located! E.g. You can hide the Help menu point from the normal user by deleting the following section from menu_user.tpl.php:

if( !empty($this->userMenu["help"])): ?>

· echo $this->userMenu["help"]["link"] ?>">

echo $this->userMenu["help"]["label"] ?>

endif; ?>

Q9 - How can add my own menu points?

<td><div class='loginMenu'><a href='url_of_the_menu_point'>
Custom menu pointa>

div>td>

You can add a custom menu point to the user menu by inserting the following section into menu_user.tpl.php:

<li><a href='url_of_the_menu_point'>
Custom menu pointa>

li>

Summary: You can change the position of elements on the interface by changing the position of the section that describes them in the template file that contains them. Click here to find out more about which template file you can find certain page elements in! You can delete elements from the interface by deleting their section from the template file. You can add new elements to the interface by adding a section that specifies them to the template file that describes the area where you want to add the new element. You can change how an element looks like by changing the content of the style sheet selector that describes the design of that element in the corresponding CSS file. Some hints and warnings:

- We are talking about HTML and CSS editing here. Even if you can perform most of these changes without a deep web-designer knowledge using only some common sense, keep in mind that both HTML and CSS have quite a strict syntax and rules that you should not break with your changes. We encourage you to edit the themes bravely, but after every change, preview the result in the browser. If you find the result unsatisfying, use the undo feature of your editor to restore the original state and experiment with a new change! It's always wise to save a backup copy of the edited files, too!
- Do you use Internet Explorer? Keep in mind that many of the visitors of your site will use other browsers and however you change a theme, the result must look properly in all the major browsers! You can even consider different screen resolutions. If you don't want to install many versions of many browsers, you can test how your site looks like in any of them using this online service.
- Don't carry this too far, however. We really don't want to encourage you to be sloppy, but we wouldn't worry too much if our site had little faults when viewed with say the Kazehakaze browser on Ubuntu Linux (sorry if you are just a Kazehakaze/Ubuntu fan)!

Q10 - I want to have more or less category columns instead of four.

A: Open the theme_config.php file in the text editor and change the number in this line:

$categoryColumnsNum=4;

Click here to learn more about the theme_config.php file!

Q11 - I have changed the number of category columns. How can I change now the width of the category panels, so that they just fit?

Q12 - How can I change the style of the lists, forms and details pages of the program?

Q13 - How can I change the style of the ad details pages?

A: You can do that by editing the pages.css file. If your changes need alterations in the HTML structure, too, you have to edit the item_details.tpl.php and item_details_sidebar.tpl.php files.

Notification management

Noah's Classifieds can send out email notifications automatically after certain user actions. The following notifications are currently supported:

1. User related notifications:
  - Sent to the user after the registration, contains the initial password,
  - Password reminder mail: contains a new password if the user forgot the old one,
2. Ad related notifications:
  - Sent to admin:

1. - - Sent to admin upon ad creation or modification
  - Sent to the owner of the ad:
    - Notification of a successful ad submission,
    - Notification of the ad approval,
    - Ad expiration warning mail,
    - Notification of ad expiry/deletion,
  - Other:
    - Auto notify email: sent to the one who has subscribed to getting emails when new ads will be submitted in a category
    - “Reply to a posting” mail,
    - “Email this to a friend” mail

Setup

So that the program can send out notifications, your server must be capable to dispatch email messages. You can check this under the 'Check' menu point any time. Note that the successful dispatch of the notification doesn't necessarily means that the email actually arrives to the recipient! It just means that Noah's itself did everything it could do to deliver the mail: it has sent out successfully and didn't get any error during this. The most frequent reason of when an email still doesn't arrives is that it has been blocked by the spam filter/firewall/etc. of the recipient party. Sometimes it can happen that the sendmail program of your server itself fails to send out the mails. In this case, you may check out the log file of the sendmail program of your server. Also, make sure that you entered a valid, existing mail address into the 'System email' field of the Settings form! This will serve as the “from” address of some of the notifications (and the “to” address of some others), so it is necessary that you supply an address there.

If you can't make the native mail sending of your server work in any way, you can also configure an SMTP server to handle it! The SMTP connection is probably the most heavily used connection, and almost certainly the most consistent and portable. You need to have a SMTP server which is capable of relaying mail from the domain of your web server for this to work. Some hosts provide a SMTP server for you as part of your package. You may also make use of Gmail's SMTP server if you have a Gmail account; however, they do impose a maximum limit of emails in any one go. You can configure the SMTP settings under the 'Mail sending properties' section of the Settings form.

In case you have issues with the mail sending, you can use the new 'SwiftMailer logging level' field of the Settings form to switch on the logging of SwiftMailer (the mailer application built into Noah's). If you enable logging, the messages will be written into the 'logs/swift_log.txt' file.

Configuring the notifications

Once you set up the mail sending, you can configure the notifications under 'Control Panel' > 'Notifications'. You can find the list of notifications there - you can click on their name to see their details and click on 'modify' to change their properties:

- CC: Specify here the email adress the notification should be sent as a carbon copy,
- Email subject: The subject of the notification. Note that you can include variables into the subject text! E.g. if you apply a subject like this: “A new ad has been submitted into $category by ${'First name'} ${'Last name'}”, the subject of a concrete notification can be this: “A new ad has been submitted into Economy cars by John Wayne”. You can read more about the variable substitution below. Also, you can specify the email subject in the email body itself, too: If the Email body field (or the email template file it references!) contains an HTML text and that HTML text has a TITLE tag, its content will be used as the subject of the email. E.g. adding the following to the 'Email body' will specify the same subject we used in the above example:

<title>A new ad has been submitted into $category by ${'First name'} ${'Last name'}title>

- Email body: the body text of the email. The body text can be an arbitrary HTML text that you can either enter into this field directly, or you can just reference to an HTML template file that contains the text. The distribution has default template files for every notifications. They are rather flat, so it's recommended that you customize them. You can find them under the 'notifications directory. You can apply variable substitution in the email body, too. More about this later.
- Active: if you don't want to use a notification, you can simply deactivate it by unchecking this field.

Some words about the internationalization: the texts of some of the notification emails can be internationalized. E.g. if a German translation of the email_to_friend.html notification template file existed and someone switched to German and then used the “send to a friend” feature of an ad, the German version of the email would be sent to the friend. To create say the German version of the email_to_friend.html template, make a copy of it into email_to_friend_de.html and translate it! The affected notifications are the following:

- email_initial_password.html - Sent to the user after the registration, contains the initial password,
- email_remind_password.html - Password reminder mail: contains a new password if the user forgot the old one,
- email_ad_replied.html - “Reply to a posting” mail,
- email_to_friend.html - “Email this to a friend” mail

Variable substitution

In the body and subject text of the notifications, you can reference to the fields of the user and the ad that is associated with the given notification. Besides the user and ad fields, you can also access some other notification specific variables. At first, lets see the variables you can paste into the text if you want to include user fields (the fields of the email recipient in case of the 'User related notifications' and the fields of the owner of the ad in case of the 'Ad related notifications'):

# This is an example only!

${'Name'} = john
${'Email'} = This e-mail address is being protected from spambots. You need JavaScript enabled to view it
${'Registration'} = 2009-02-19
${'Last log in'} = 2009-02-19
${'Ads of this user'} = Click here to view the ads of this user!

# The below variables correspond to the the custom fields of the users that come with the distribution.
# Of course, the custom fields in your installation can be completely different - it's just up to you how you configure them!

${'First name'} = John
${'Last name'} = Wayne
${'About me'} = This is a test user only, whose sole purpose is ...
${'Street'} = Apple st. 15
${'Post code'} = 55555
${'City'} = Chicago
${'State'} = Arizona
${'Country'} = United States
${'Age'} = 77
${'Married'} = Yes
${'Date of birth'} = 1931-10-23
${'Picture'} =
${'Picture 2'} =
${'Picture 3'} =

In the ad specific notifications, you can include any field of the ad the notification is associated with. They are the following:

# This is an example only!

${'listing'} = Audi TT
${'plainTitle'} = Audi TT
${'title'} = Audi TT (clickable link)
${'breadcrumb'} = Home » Cars » Economy cars » Audi TT (all pieces are clickable links)
${'wholeCatName'} = Cars - Economy cars
${'category'} = Cars
${'daysLeft'} = 10
${'description'} = A brand new car
${'url'} = http://yoursite.com/item/21
${'ID'} = 21
${'Created'} = 2009-02-19
${'Status'} = Active
${'Views'} = 0
${'Responses'} = 1
${'Expiration'} = 10

# The below variables correspond to the the custom fields of the ads in the given category.
# Of course, the custom fields in your installation can be completely different - it's just up to you how you configure them!

${'Title'} = Audi TT
${'Description'} = A brand new car
${'Consumption'} = 10.00 l/mile
${'Broken'} = No
${'Price'} = $ 100.00
${'Picture'} =
${'Pic2'} =
${'Promotion level'} = Gold

Some notes:

- If the name is the field is simple (i.e. doesn't contain spaces or other non-word characters), you can use a simpler notation. E.g. You can use $Picture, $Consumption, $Price instead of ${'Picture'}, ${'Consumption'} and ${'Price'} (but you couldn't use say ${'First name'} without the braces!),
- In case of name collisions (e.g. if the ad has a 'Picture' field and the owner of the ad has a 'Picture' field, too), you can use the following notation: ${'item:Picture'} refers to the Picture field of the ad and ${'owner:Picture'} refers to the picture field of the user.
- The variables that refer to a picture type custom field will be substituted with the clickable thumbnail picture. So, you can really add the picture fields as images to the notification emails. Note, however, that including external images into a mail text always increases the chance that the notification will be blocked by the spam filter of the recipient!

Further variables you can use (they can be only used in the given notification!):

- email_ad_reply.html:
  - $message: the text of the message,
  - $name: the name of the sender,
  - $email: the email of the sender
- email_to_friend.html:
  - $message: the text of the message,
  - $name: the name of the sender,
- email_initial_password.html and email_remind_password.html:
  - $name, $uname: the user name,
  - $pwd, $Password: the password of the user,
  - $url: the login link
- email_subscription.html:
  - $unsubUrl: the unsubscribe URL

Finally, let's see an example of a body text that applies many of the above variables (it is of a category subscription notification):

<html>
<head>
<title>A new ad has been submitted in '$category'title>

head>
<body>
<h2>The following advertisement has been submitted in the category you subscribed for:h2>
<table>
<tr>

<td>Title:td><td>$titletd>
tr>
<tr>

<td>Category:td><td>$breadcrumbtd>
tr>
<tr>

<td>Description:td><td>$descriptiontd>
tr>
<tr>

<td>Picture:td><td>$picturetd>
tr>
table>

The ad has been created on $Created and will expire in $daysLeft days.<br>
Some details about the advertiser:<br>
<ul>
<li>Name: ${'First name'} ${'Last name'}li>

<li>Location: $Street, ${'Post code'}, $City, $State, $Countryli>
<li>${'Ads of this user'}li>
ul>
And this is the photo of the advertiser:<br>

${'owner:Picture'}<br>
<br>
<a href='$unsubUrl'>Click here to unsubscribe from getting notifications on ads created in the '$wholeCatName' category!a>

body>
html>

Advanced usage

If the plain HTML notifications wouldn't provide enough flexibility, you can also use Php templates. E.g. use this in the 'Body' field of a notification: notifications/email_ad_replied.php and you can write the following into the named email_ad_replied.php file:

if( "${'owner:Gender'}"=="Male" ): ?>

elseif( "${'owner:Gender'}"=="Female" ): ?>

endif ?>

.... mail text

The above example sends the email with blue background if the owner of the ad is a male and with pink background otherwise.

Overview of the Noah's eCommerce edition

The purpose of the eCommerce edition is to make it possible for you (as the site owner) to move from a “free classifieds” site to a paid one. You can collect payments from your users on certain actions - most typical of which is the ad submission. Inside this frame, you can configure the program quite flexibly, in order to set up your unique business concept. The automatic payment collection is supported by payment processing gateways integrated into Noah's. The two we have added are Authorize.NET and PayPal.

The Noah's eCommerce edition is NOT the following:

- It's not something that you can use to build an online shop (for now!). You can't set up the ads so that they contain your goods with a buy button that the visitors can use to purchase those goods. (Or course, you could have already added tricks that realize this functionality and the eCommerce edition won't take these away from you, but the point is that this functionality is not yet supported “out of the box”)
- It's not an eBay-like program (for now!). Your users can't set up the ads to sell their own goods to other users while you take a commission from that.

The program supports two different approach to set up a paid classifieds site - we call them eCommerce models. The first one is the “Simple model” - it's more traditional, but less flexible, while the “Advanced model” is more flexible, but less straightforward:

- Simple model: with this, you can set up the program so that the users must pay for submitting ads directly right after the ad submission itself. They must pay as many times as many ads they submit.
- Advanced model: with this, you can set up a credit based, or subscription based system (or you can even apply both at once!)
  - Subscription based model: the users buy a subscription for a certain amount of time and during that, they can do whatever they want for free.
  - Credit based model: the users buy credits and from their credit pool, they can spend some to perform certain actions. You can specify which actions cost how many credits.

No matter which model you choose, you must configure the built in payment processing service the same way. Theoretically, it is possible to use the Advanced model without the built in payment processing facilities of Noah's (because admin can manually give users subscription time, or credits), but that way, the program would lose its “real-time” automatism.

Upgrade and testing: so, what if you have an existing Noah's Classifieds installation and you upgrade to the eCommerce edition? What if you don't even need eCommerce at all, because you want to keep your site free? Does it make sense to upgrade in that case at all? Yes, it does, because this new release has many useful eCommerce independent other new features, too, that make it worthwhile to upgrade anyway! If you don't enable eCommerce in Noah's, neither admin, not the users will see anything eCommerce-related on the site, so it is completely safe to use the program furthermore as a free classifieds if you decide so.

What if you do need the eCommerce features, but you want to properly test their set up before you go live with them? This is possible, too, because the eCommerce edition has a special “test mode”! In test mode, admin can configure all the eCommerce settings as if eCommerce was really enabled, but the only user that this has some effect on is a special one called “ecommtest”. If the program is in test mode, all your existing users can use the site just as they always did, but you can log in as 'ecommtest' and try out what your users will experience as soon as you enable the eCommerce eventually!

You can proceed to the Below to learn more about the configuration of your eCommerce edition.

eCommerce configuration

Noah's supports two substantially different ecommerce models, which we call Simple and Advanced model. Choosing one of them at the beginning of the ecommerce configuration is one of the most important decision you must make.

- With the 'Simple' model, you can set up the program so that the users must pay for submitting ads directly during the ad submission itself.
- With the 'Advanced' model, you can set up a credit based, or subscription based system (or you can even apply both at once).

Both models require an integrated payment processing gateway. The first one we have implemented is that of Authorize.NET. There are two different methods to integrate a payment processing service into your site. The decision basically depends on whether your server supports Secure Sockets Layer (SSL) and you have an SSL certificate. If it does and you have, AIM is the preferred way of the integration. With AIM, your customer can stay on your site during the payment process. The configuration of AIM is much simpler, too. As opposed to this, in absence of an SSL certificate, you must choose the Server Integration Method. With SIM, the collection of credit card information occurs on the secure hosted payment form of the processing service itself.

Our second built in gateway - PayPal - has its two integration methods, too: Website Payment Standard and Website Payment Pro. The differences are fairly similar to that of the SIM and the AIM discussed above. You can find out more about them in the PayPal documentation.

The fist one of the following two tutorials demonstrate the setup of the Advanced model with SIM integration method, while the second one shows the Simple model with AIM (of course, the Simple model-SIM and Advanced model-AIM variations are possible, too!)

You may also want to check out this other tutorial -Below-: Configuring paid featured ads

Advanced model with SIM integration method

(Just a note: We -Did Not- Use light Box for the Pictures Below. We have it open a new Window as it helps keep Focus for the Purpose of you working the Configuration).

001

002

003

004

005

006

007

008

009

010

011

012

013

014

015

016

017

018

019

020

021

022

Tutorial: configuring paid featured ads

In this slideshow, you will learn how to create an e-Commerce model where you charge for the featured ads. The steps we show in details are the following:

1. Create a new 'Highlight my ads' custom field,
2. Create a credit rule based on this field,
3. Test the ad submission as 'ecommtest',
4. Make a scrollable widget for the featured ads

We use the “Advanced model” in this tutorial, but it can be applied to the simple one with small modifications, too.

Installation Video

Category & Sub-Categories

SEO in NOAH

Custom Fields

Youtube in Noah

Google Maps

RSS & XML

Category Organizer

Video How-to's