OpenRealty 3.0

by Jon Roig (jon@jonroig.com)
Release 7-1-2002

LATEST VERSION:
http://jonroig.com/freecode/openrealty/

PLEASE READ THIS ENTIRE FILE BEFORE INSTALLING OPENREALTY

(Thus, you will avoid my wrath when you ask a question answered in this FAQ)

Support and News

http://jonroig.com/freecode/phpBB/
 

I DO NOT HAVE TIME TO ANSWER QUESTIONS VIA EMAIL! Please post all comments, questions, etc... to the message board and I will respond as quickly as possible. Also, you might try reading through the posts -- your question may be answered already.

I do, however, have time for consulting gigs from time to time. If you need a hand with customization or installs, feel free to drop me an email at jon@jonroig.com. I think you'll find my rates are reasonable and that I'm an easy guy to work with...

This is Free?

OpenRealty is 100% free. You will never be charged a cent to use it and there are no restrictions on its use. There are no hidden catches -- all we ask is that you leave the hidden comment in that appears on every page generated by OpenRealty intact. This is my calling card, so it's very important to me that I get recognition for my work.

This is a fun project to work on. I enjoy it. Frankly, I get a kick out of seeing sites all over the world running my script. A strange hobby, maybe... but one has to do something during the hours away from work. ('Sides, the chicks LOVE it)

If you want to contribute to the project, there are several ways you can do so:

• Find bugs and report them on the forums!
• Hack code! Got an improvement? Share it with the rest of the world (literally).
• Translate the english.php include file to your native tongue -- post on the forums if you can help with this.
• Purchase something off my Amazon wedding registry. Like I said, the chicks love open source programmers, but sometimes my fiance can't understand why I forgo sleep to work on this. Bribe her with stuff and she'll let me work more. :)

Using and Installing OpenRealty

1. Download OpenRealty. Unzip the file.
2. Create a new folder on your server.
3. Configure and set parameters (explained below).
4. Upload the contents of the zip file to your server.
5. Create and configure your database tables (also explained below).
6. Go on to live a healthy, happy, real-estate driven life...

Required to run Openrealty

1. MySQL or another database
2. PHP 4 or better

Summary of Functionality

This system is intended to become a toolkit for listings sites. Whether you're listing real estate, autos, penpals, or churches, this tool should help you along your way. Here's a basic overview of the functionality.

• Allows visitors to look through your real estate listings 24 hours a day, 7 days a week, 365.25 days a year.
• Easily keep your property listings updated -- no HTML coding required to add, delete, or modify listings.
• Built-in image manager -- upload photos via your web browser, either when creating new listings or modifying an existing one. If photos are not uploaded for a property, a "photo not available" image will be automatically displayed for the listing.
• Automatically thumbnails -- smaller versions of your images are automatically created through the GD library.
• Automagically interfaces with Yahoo Maps -- potential customers will always know exactly where to find your property.
• Flexible database backend -- compatible with mysql, oracle, microsoft SQL, etc... through the ADODB abstraction layer.
• Secure -- no one but you can change your listings.
• Viral Marketing -- visitors can email listings to their friends right from OpenRealty.
• Easy to install -- just edit a single configuration file.
• Showcase specific properties -- built-in featured listing manager allows you to place special offerings right on your front page.
• Flexible search -- browse properties according to whatever criteria you like.
• Easy setup -- configurator tool makes OpenRealty 3.0 easy to install.
• Configurable forms -- Don't like the form choices included in OpenRealty? Change them to meet your needs!
• Template system -- produce a sophisticated site without any knowledge of PHP
• Supports CSS stylesheets.
• Multilanguage capable (coming soon -- I need help with translation!)

Changes Since Last Version

This version of OpenRealty is a complete rewrite of the OpenRealty engine. Based on a system I wrote called OpenListings, this is the first use of my new listings engine. Designed to be completely flexible, OpenListings allows you create fully featured listings sites for whatever you want to put online, be it homes, or cars, or airplanes, or pets.

The changes are almost too numerous to mention -- templates, automatic thumbnailing of images, configurable forms, improved password handling, etc... the list goes on and on...

This should always be considered a work in progress. Spot a bug? Let us know in the forums. It has been because of the community involvement of people all over the world that this project has been as successful as it has.

Plans for next version

• XML/web services export/import
• True, simultaneous multi-language capability.
• "Notify me when a listing that contains XXX becomes available"
• Paypal integration/more advanced moderation facilities
• What else...? Let us know in the forums...

Getting Started

1. Obviously, you've already unpacked the file, or you wouldn't be looking at this.
2. You need to CHMOD the contents of the images folder to 777, including the listing_photos and user_photos subfolders. This is where your images are stored.
3. Edit the /include/common.php file. (More on this in a moment...)
4. Set up a database that OpenRealty can use. (Again, see below...)
5. Run the configurator. If everything goes alright, you should be able to log in:
   Default login = admin
   Default pass = password
   
   You should change this password ASAP.

The common.php File

In the include directory, you should find the common.php file. This file contains all the settings for OpenRealty. Open it up with your favorite text editor and you should see a whole bunch of settings...

For those of you who are new to the world of PHP, don't be scared. We could have put all these settings into a database or something, but we'd take a hit in performance with all those extra queries...

... and you like speed, don't you...?

Make a backup copy before you do anything drastic and maybe just adjust one thing at a time. Although each item has an explanation next to it, I might be able to shed some additional light on how this works...

SITE INFORMATION
This area is where you set up the base info for your site. This includes information like your site's address, the basepath (where the files are located on your server), your name, email address, and the site's name. Make sure you leave the trailing slash off the basepath and url, or everything will get all messed up.

The most common error has to do with the distinction between basepath and baseurl. The baseurl is the actual web address that users see -- IE, http://jonroig.com/freecode/openrealty

The basepath, however, is for your machine's use only -- it's the physical location of the openrealty scripts on your box. You'll know instantly if you got it wrong, because it'll give you an error that looks like:
Warning: Failed opening '/template/generic/style.php' for inclusion (include_path='') in /usr/www/users/linuxuser/openrealty/include/common.php on line 42

Here's a little trick: in the example above, "/usr/www/users/linuxuser/openrealty" is the correct basepath. Make sense?

DATABASE TYPE
You may not have to set anything here -- it depends entirely on what kind of database you choose to use. Because we're using the ADODB database abstraction library, you pretty much get your pick of databases. Nice, eh?

Possible choices are: access, ado, db2, ado_access, vfp, fbsql, ibase,firebird, borland_ibase, informix, mssql, mysql, mysqlt, maxsql, oci8, oci8po, odbc, oracle, postgres, postgres7, sqlanywhere, sybase

It might be worth noting that we really haven't tried it too extensively with some of the more exotic databases out there... so if you're using anything other than postgres, mysql, or mssql, let us know. I'd be curious to hear if you have any problems...

This is also where you set up your database user name, password, the db name, and the server to use.

TEMPLATE DATA
This is where you set up the path to the templates. Eventually, we hope to develop a wide variety of different styles that can just be dropped into place. For the initial release, I'm distributing one style. It's plain... admitted rather boring... and we call it "generic."

Probably, you won't have to mess with these settings, at least at first. The template_path refers to the internal server path to the folder, while template_url is for browsers to hit things like the CSS file. There's an explanation of all the files later in the document.

If you do take it on yourself, make sure you leave the off the trailing slashes or everything will crash and you will cry. (We'd rather have you crying tears of joy, rather than frustration.)

LANGUAGE FILE PATH -- USED FOR MULTI-LANGUAGE SUPPORT
This distribution of OpenRealty contains only one language file, but we hope to make more available for download soon... If you can help translate the english.php file, post a message on the forums (so people don't duplicate each other's work).

Ultimately, we hope to make OpenRealty as universal as we can... Also, as of right now, OR only supports one language at a time (no multilingual sites), but that's something we'll improve on ASAP.

DISPLAY SETTINGS
European users rejoice! You can now change the money sign that appears by default. We also now support a wide variety of numbering formats, designated by numbers you put in for the $config[number_format_style] in the common.php file:

• 1 - Good old American formatting -- 123,456.78 (for the blokes in the UK, too)
• 2 - Spain/Germany -- 123.456,78
• 3 - Estonia -- 123 456.78
• 4 - France/Norway -- 123 456,78
• 5 - Switzerland -- 123'456.78
• 6 - Kazahistan -- 123 456-78

Thanks, Satoko, for cluing me into the mysteries of the international numbering system.

Next up is the way that prices are displayed... since you've already set your money sign, there's a little function called "money_format" that displays it properly. The default is the US/UK, but I've left it open, so you can do whatever you need to do to make it work for your native land.

UPLOAD SETTINGS
OpenRealty now contains a thumbnailing engine that works with the GD library -- this is usually included with most linux-based hosting plans, you never know. Windows users will probably have to change $config[make_thumbnail] to "no". If you get a "undefined function: imagecreatefromjpeg()" error, then you know that you have to turn this option off.

Now I know what some of you are thinking... why GD? Why not imagemajick -- it can handles GIF files as well as jpg and png. The reason is simple. I don't have it on my test machine. If someone wants to write an imagemajick thumbnailler, let me know. It should be pretty straightforward, and it is something I'd like to include.

LISTING EXPIRATION SETTINGS
You can now set up OpenRealty so that listings expire automatically after a set amount of time. The settings should be pretty obvious.

USER SETTINGS
In an effort to give administrators more fine-grained control over OpenRealty, we developed a new user settings area. You can make it so users can't sign up for the system -- instead, all new users would have to be created through the administrative tool.

I also added a bunch of default privileges for new users. Maybe you want all the users to be able to view the logs for some reason, I don't know... I figured it would be better to create the option than live a life of regretting that I had not done so.

MODERATION SETTINGS
This is a popular one. OpenRealty now supports a moderated setting -- if you flip this on, listings will require an administrator to flip them on. Inactive listings can be previewed by either the listing's creator or an admin, but the general public will not be able to see them.

You can also set OpenRealty to email you when someone adds a new listing. This email will go to the address you defined way back in the USER SETTINGS section.

MISCELLENEOUS SETTINGS
In general, you shouldn't have to mess with these files... If you don't know what they are, leave 'em alone.

Setting up the database

Due to OpenRealty's use of the ADODB Database Abstraction Layer, OpenRealty can support a wide variety of different databases. It cannot, however, create the database for you. You must first create a database through your preferred method -- usually, this is something like phpMyAdmin for folks with mysql or the enterprise manager for those of you blessed with microsoft sql servers. Your mileage may vary -- my host, for instance, makes me use their tool to add mysql. They're trying to limit me to a single mysql db.

For those power users out there, you actually have to grant OpenRealty the ability to create databases -- it uses a temporary table to do the sorting on the listingssearch.php page.

The Files

What do all these files do... well... let me tell you about it.

• /openrealty
• email_listing.php - Allows users to send listings to friends
• index.php -- The main index page -- contains the featured listings, etc...
• listing_browse.php -- The search form page (more on customizing this below)
• listingsearch.php -- Displays search results
• listingview.php -- Displays a given listing's data (customization info below...)
• readme.html -- This file. You're looking at it.
• user_form_submit.php -- The receiving end of the form on user_signup.php
• user_signup.php -- Lets users sign up for your site (if you let them)
• userview.php -- Displays info about a given user
• viewimage.php -- Displays images attached to users or files
• /admin
  • add_listing.php -- Add a listing to the site
  • add_user.php -- Add a user to the site
  • edit_listings_images.php -- Add or edit a given listing's images
  • edit_my_account.php -- Edit user data for non-admins
  • edit_my_listings.php -- Edit listings for non-admins
  • edit_user_images -- Add or edit a given user's images
  • emailpass.php -- Lost your password? Retrieve it here...
  • index.php -- A pretty much blank page
  • listings_edit.php -- Allows admins to edit listings
  • log_view.php -- Almost all administrative activities are logged -- read the logs here
  • logout.php -- Log out after you've finished your session
  • moderation_queue.php -- View inactive items on the site
  • template_editor.php -- Edit the listings templates
  • user_edit.php -- Allows admins to edit users
  • user_form_editor.php -- Edit the user form templates
• /images
  • nophoto.gif -- The default "No Photo Available" image
  • /listing_photos -- Contains all the images connected to listings
  • /user_photos -- Contains all the images connected to users
• /include
  • common.php -- The main settings for the site
  • main.php -- Shared code for the site. Don't mess with this unless you know what you're doing...
  • thumbnail_gd.php -- The default thumbailing tool
  • /adodb (this is this ADODB database abstraction library -- you shouldn't have to mess with it)
  • /language -- languages supported by OpenRealty
• /template/generic
  • admin_bottom.html -- The bottom template for the admin area
  • admin_top.html -- The top template for the admin area
  • style.css -- All the css style defs for OpenRealty
  • style.php -- All the template code and misc look and feel defs for OpenRealty
  • user_bottom.html -- The bottom template for the user area
  • user_top.html -- The top template for the user area

Customizing OpenRealty

I've tried to document the code as much as possible to aid with customization... but most of what you're probably looking for will be in the /template/generic folder. The idea here is that you could distribute an entirely different system by only swapping out that folder.

Styles and Stylesheets

You can control a lot of the look and feel of the system through the info contained in the style.php and style.css files. Editing them should be reasonably straightforward...

Form Setup

If you login as admin/password, you'll have access to the form editors. Please take a few moments to examine the example before you mess with it... but let me break it down for you:

• Field Name: The name of the field. Users won't see it, so keep it to a single word.
• Field Type: What type of field is it? You have the following choices:
  • Text -- Standard single line text input box.
  • Textarea -- Multi line text input area.
  • Select List -- Pulldown list
  • Select Multiple -- Select where you can choose multiple items
  • Option Box -- Radio buttons
  • Check Box Divider -- List of items with checkboxes (like for features)
  • Price -- Text-type input, but automatically formatted as $amount. (or whatever, you can control this via the common.php file)
  • URL -- Text-type input, but auto formats the url.
  • Email -- Text-type input, but auto formats the email address.
  • Number -- Text-type input, but auto formats the number to include commas
• Required: Does the user have to fill this out to submit/update a listing?
• Field Caption: This is that the user sees next to the item
• Field Elements: What are the choices for select lists and option boxes? Separated with double bars like so: Alabama||Alaska||Arizona
• Default Text: Should the form have some pre-defined text in it when the form is first viewed?
• Display Location: This corresponds with the built in template system. Where on the listingview.php page should this item appear? You have the following choices: top_right, top_left, bottom_right, bottom_left, headline, center, feature1, feature2
• Display When Browsing: Choosing "yes" here will include this item as a column on the search page. If the form item is a text area, then it'll display on it's own line on the search results page.
• Rank: The lower the rank, the closer to the top of the page it'll appear.

Templates

To aid non-php-type folks, I've added a number of little functions to the /template/generic/style.php file. These are then called on the listingview.php userview.php pages as part of a kind of template system. This should not be considered finished -- I need to centralize it all a bit and add one or two more functions...

The actual code for these functions is located in the /include/template/generic/style.php file.

Let me run down the list of options -- you'll find examples of how to use these functions in a given page's code:

In Listingview.php you can call the following functions:

• renderListingsImages($listingID) This outputs the listing's images in a vertical column.
• renderSingleListingItem($listingID, $name) Let's say you only want to output a single item in a listing -- like, say, zip code or something. You would do that like so: renderSingleListingItem($listingID, "zip")
• renderSingleListingItemNoCaption($listingID, $name) Like the example above, but instead of outputing "Zip: 90210" it will simply output "90210"
• renderSingleListingItemRaw($listingID, $name) This is sort of like renderSingleListingItemNoCaption except the script makes absolutely no effort to format the data being spit out. Handy if you have to plug a variable into a popup mortgage calculator, for instance.
• renderTemplateArea($templateArea, $listingID) Relates to the template system -- shows all the items for a given template area.
• renderTemplateAreaNoCaption($templateArea, $listingID)Same as above, but without the corresponding captions.
• getMainListingData($listingID) Outputs the title of the listing and the user who created it.
• hitcount($listingID) This allows you to add a hit counter to any listing.
• renderUserInfoOnListingsPage($listingID) Include information about the user who created the listing.
• getListingEmail($listingID) Include the email address of the user who created the listing.
• makeYahooMap($listingID, $address_field, $city_field, $state_field) Builds a link to Yahoo maps. The various fields refer to the names of field setup through the template building tool.

In userview.php you can call the following functions:

• renderUserImages($user) Outputs a given user's images in a vertical column.
• renderUserInfo($user) Outputs the information attached to a user.
• getMainUserData($user) Shows the name of the user.
• getUserEmail($user) Shows the email address of the user.

listing_browse.php, the main search page in the demo, has these functions to help you:

• browse_all_listings() This simply outputs a link to browse all the listings with the number of available listings.
• searchbox_select ($browse_caption, $browse_field_name) Outputs a search multiple select box containing the elements and caption of your choice. Should be contained within a table.
• searchbox_select_vert ($browse_caption, $browse_field_name) Just like searchbox_select, except it doesn't need a table and the caption is located above the select box.
• searchbox_pulldown ($browse_caption, $browse_field_name) Same as above, but with a pulldown menu. There's also a corresponding searchbox_pulldown_vert.
• searchbox_checkbox ($browse_caption, $browse_field_name) Sensing a trend here? This lets you build a search box with checkboxes. You can also, by the way, use searchbox_option ($browse_caption, $browse_field_name) if you want radio buttons. For that matter, there are also searchbox_checkbox_vert and searchbox_option_vert functions, too.
• renderFeaturedListingsVertical($num_of_listings) This displays however many featured listings you'd like in a vertical column. A horizontal version will be in the next revision...
• latestListings($num_of_listings) This lists the latest X number of listings.

By the way, you can add these functions anywhere. If you want to layout search boxes horizontally rather than vertically, just through a table tag around each of the searchbox functions.

Licensing Info

OpenRealty is OpenSource and released under the GNU Public License.

Feel free to use it for whatever you like -- sell it, customize it, turn it into something different, anything is possible. All I ask is that you leave the hidden comment about myself and the tool's origins intact. If you want to be really cool, feel free to put a link to my site somewhere on your site.

Other licenses are available for this software, so if you want to remove my copywrite info from the code for some reason, get in touch with me and we'll talk.

Conclusion

I just want to take a moment to thank everyone who's helped out on this project, whether it's contributing code, assisting other users in the forums, or just generally being encouraging. I hope you already all know how much I appreciate it.

A special shoutout goes to Jason Dulberg -- he's been a supporter/contributor to the project for awhile, essentially keeping it going while I was fully immersed in my day job.

Any bug reports and/or suggestions will only make this project better. Post 'em to the forums....

Changelog

V 3.01 (07-06-2002)

• Fixed problem with allowed HTML in text fields.
• Occasionally the PHPSESSID would throw off the search results. NO MORE!
• Cleaned up the search results code a tiny bit.
• Fixed problem with image uploads on machines that use safe_mode.
• On the listingsearch.php page, and textarea item marked "Show on Browse" will display on its own line.
• When you delete a listing now, it deletes all the images associated with it.
• When a user is deleted, the user's listings are all deleted, along with any images associated with them.
• Added support a default image if no image is available.
• You can now allow users to edit their own listing's expiration dates, if you like.
• Speaking of expiration dates, listings expire properly now.
• Upgraded to ADODB 2.12 (details @ http://php.weblogs.com/ADODB.
• We now support international numbering and money amounts.
• Added new functions: renderSingleListingItemRaw, latestListings.
• New translations: German, Spanish, French, Italian, Finnish, Swedish.
• Completed support for Access databases (I think).

Newsgroups: php.general
Path: archiver1.google.com!news1.google.com!sn-xit-02!sn-xit-01!supernews.com!
yellow.newsread.com!netaxs.com!newsread.com!newsfeed.media.kyoto-u.ac.jp!opentransit.net!
fr.clara.net!heighliner.fr.clara.net!news.imp.ch!news.imp.ch!imp.ch!news.php.net
Return-Path: < j...@gokart4xmas.com>
Mailing-List: contact php-general-h...@lists.php.net; run by ezmlm
Delivered-To: mailing list php-gene...@lists.php.net
Reply-To: < j...@gokart4xmas.com>
To: < php-gene...@lists.php.net>
Date: Mon, 1 Apr 2002 07:35:05 -0500
Message-ID: < JDEIIJGKCLDGDMAIDALMCEEJDDAA.jon@gokart4xmas.com>
MIME-Version: 1.0
Content-Type: text/plain;
	charset="iso-8859-1"
Content-Transfer-Encoding: 7bit
X-Priority: 3 (Normal)
X-MSMail-Priority: Normal
X-Mailer: Microsoft Outlook IMO, Build 9.0.2416 (9.0.2911.0)
X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2600.0000
In-Reply-To: <1017601360.3ca75d50a0e62@mail.gurubase.com>
Importance: Normal
Subject: Programming Methodology Question
From: j...@gokart4xmas.com (Jon)
References: <1017601360.3ca75d50a0e62@mail.gurubase.com>
Lines: 26

Hey --

I have a question for ya'll.

I'm writing a fairly substantial program which allows listing of items like
real estate, car ads, etc... on the web. Overall, it looks like it'll be
around 5-7000 lines long.

I was thinking about putting the main guts of it into one big include file
to make it easier to upgrade when we release new versions. Is that
problematic, to have a php file that large? (I mean, I know it's not THAT
big.) Should I break it into separate files, maybe just make a folder
replaceable?

Thanks,
	-- jon



-----------------
jon roig
jon at jonroig.com
project manager, OpenListings
http://jonroig.com

Copyright 2002