Open-Realty Installation Readme

by Ryan Bonham (ryan@open-realty.org)
Get the latest version:
http://open-realty.org/

PLEASE READ THIS ENTIRE FILE BEFORE INSTALLING OPENREALTY

Support and News

http://open-realty.org/phpBB2/

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 ryan@open-realty.org.

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.

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.

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

Getting Started

1. You must have your php install setup to use register_global = on.
2. Obviously, you've already unpacked the file, or you wouldn't be looking at this.
3. 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.
4. Edit the /include/common.php file. (More on this in a moment...)
5. Set up a database that OpenRealty can use. (Again, see below...)
6. 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 Ulei de trandafir 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 or ImageMagick -- 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.

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
• Calc.js -- This is the javascript file for the mortgage calculator
• Calc.php -- This is the php page that recieves the listing price and displays the mortgage claculator
• email_listing.php - Allows users to send listings to friends
• index.php -- The main index page -- contains the featured listings, etc...
• legal.php -- This page displays the legal warnings, it reads teh company name from common.php
• 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.
• openlistings.sql -- This is teh sql file, for creating the database
• 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
• view_users.php -- Displays a list of all users, except Admin
• /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
  • equalhousing.gif -- The "equal hosing oppertunity" logo.
  • 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
• /template/vertical-menu
  • /images -- This directory contains all the images needed for this template.
  • admin_bottom.html -- The bottom template for the admin area
  • admin_top.html -- The top template for the admin area
  • menu.php -- The vertical button menu that is displayed on the page
  • 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 view_users.php you can call the following functions:

• getAllUsersData() This ouptus a listing of all the agents in a vertical column, with pictures to the left, it skips the "admin" user.

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.

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 thank you goes to everyone that contributed to Jon's OpenRealty, for ultimatly making such a great piece of open source software.

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