The most difficult part about configurating this package is making a connection
to the MLS server. Even with standards like RETS there are enough variations
between server vendors to cause frustration. A configuration file is used to
specify how the package communicates with the MLS server and specifies options
for your connection.
Source configuration files are plain text format and can be found at
{INSTALLATION_DIRECTORY}
/
{SOURCES_DIRECTORY}
/{SITE_NAME}. The SITE_NAME is specified when a
Source is
defined
. If you have multiple Sources defined, there will be more than one file
in the SOURCES_DIRECTORY. It is a good idea to keep a backup of
Source configurations in this directory.
You need a Source defined for each MLS you would like to connect to. If you
only plan to connect to a single MLS you will need one of these files, even
if you plan to support multiple Broker/Agent sites. The settings shipped with
the distribution will connect to the demonstration server operated by the
Center for REALTOR® Technology
, a division of the National Association of REALTORS®.
As this package matures, attempts are being be made to "auto-detect" as many of these
variables as possible.
This file has different sections that are used to divide configuration
information into logical groups:
|
Connection
This section identifies which RETS server you are connecting to. You will
need to obtain the information for these settings from you service provider.
The distribution provides defaults that allow you to connect to the
demonstration server operated by CRT.
- RETS_SERVER_ACCOUNT - The name of the RETS account. Defaults to
"Joe".
- RETS_SERVER_PASSWORD - The password of RETS account. Defaults to
"Schmoe".
- RETS_SERVER_URL - The URL of the RETS server. Defaults to
"http://demo.crt.realtors.org:6103/rets/login".
- RETS_DEFAULT_PORT - The port to use if the RETS server is not
specific during its reply to a login. The RETS specification identifies 6103
as the default port, but in practice, many providers use 80. This is probably
because the HTTP default is 80. Defaults to "80".
- KEEP_ALIVE_SERVER - Specify whether the RETS server supports
keep-alive tcp sockets. This is a new capability added as of Version 1.1.
Setting this to "true" will result in avoiding setting up a new tcp socket
between this package and the RETS server for each communication and will
result in higher performance. Not all RETS servers support this capability.
If you are not sure, leave it as "false". Defaults to "false".
- ENCODE_REQUESTS - Specify whether the RETS server supports
requests that are URL Encoded. Typically this is set to "true". If you
use the default value and have problems executing queries that have values
with spaces (like area="Hidden Oaks") then try setting this to "false".
Defaults to "true".
- POST_REQUESTS - Specify whether the you want to use POST or GET
style HTTP requests. Some older servers have a problem with long GET style
requests and even construct Digest Authentication incorrectly with GET. If
you are trying to return more than 60 fields for any one listing and the
package fails, but bringing back 10 fields works, then you might want to
leave this set to "true". Defaults to "true".
The following setting is auto-detected by the package.
- DETECTED_SERVER_NAME - The name of the server derived from the HTTP
headers. This value is set by the server you are connected to.
|
|
|
Auto-Detection
This section described the auto-detection capabilities of the package. The
performs multiple logins to the server and trys to detect capabilities. Before
auto-detection can proceed, you will be prompted for information related to
User-Agent identification. Your service provider may use the HTTP User-Agent
header to control connects to their server.
The User-Agent has two components and is structured in the following format:
<![CDATA[APPLICATION/VERSION]]>
If you were given a User-Agent value by you service provider, now is your
opportunity to change the default values used by the package.
- APPLICATION - The network identification (name) of this client for
use within the HTTP protocol. If you change this, make sure that you only use
one word. Defaults to "VieleRETS".
- VERSION - Part of the HTTP client identifcation that signifies
version number. You can leave this blank if the User-Agent supplied to you by
the MLS is not in the form APPLICATION/VERSION. Defaults to "1.0".
The next screen prompts you for the resource to use with this source.
- SELECTION_RESOURCE - The RETS resource to use for a query. The RETS
standard identifies "Property" as the common name for this. This setting is
also used for both
Text Query
and
Media Query
requests.
Now that the User-Agent and resource are identified, the package will prompt
you to choose a class for the requested resource.
- SELECTION_CLASS - The RETS class to use for a query. The RETS
standard does not identify a common name. This setting is highly dependent on
your service provider. The demo server that CRT opertates has data in only
one class, "RES".
The following settings are then detected. There are no default values for
these settings and they are presented in the order that they are detected.
- DETECTED_DEFAULT_RETS_VERSION - The default version of RETS that
this server supports. This value can be 1.0, 1.5 or 1.7.
- DETECTED_STANDARD_NAMES - If the server you are using supports RETS
Standard Names, this value is set to "true". This setting affects the values
for the following
Text Query
settings:
- OWNERSHIP_VARIABLE
- QUERY_ITEMS
- DETAIL_ITEMS
- GALLERY_ITEMS
- SUMMARY_ITEMS
- DETECTED_MAXIMUM_RETS_VERSION - The maximum version of RETS that
this server supports. This value can be 1.0, 1.5 or 1.7.
- UNIQUE_KEY - The name of the data element that is the unique key for
the data. This is typically the listing number for property data. This value
is highly site dependent.
- PAGINATION - Some servers do not support enough of the RETS standard
to allow query results to be packaged into pages for easier viewing.
|
|
|
Override Auto-Detection
Although the package has the ability to auto detect capabilities of the server,
sometimes it is necessary to change these values. The following values can be
changed:
- DETECTED_STANDARD_NAMES - If the server you are using supports RETS
Standard Names, this value is set to "true". This setting affects the values
for the following
Text Query
settings:
- OWNERSHIP_VARIABLE
- QUERY_ITEMS
- DETAIL_ITEMS
- GALLERY_ITEMS
- SUMMARY_ITEMS
- SELECTION_RESOURCE - The RETS resource to use for a query. The RETS
standard identifies "Property" as the common name for this. This setting is
also used for both
Text Query
and
Media Query
requests.
- SELECTION_CLASS - The RETS class to use for a query. The RETS
standard does not identify a common name. This setting is highly dependent on
your service provider. The demo server that CRT opertates has data in only
one class, "RES".
- UNIQUE_KEY - The name of the data element that is the unique key for
the data. This is typically the listing number for property data. This value
is highly site dependent.
- COMPACT_DECODED_FORMAT - If the server you are using supports RETS
Standard COMPACT-DECODED format, you should set this value to "true". When
set to "true", data fields that are comma separated lists (like "features")
will be expanded to a more verbose form by the server. If you set this value to
"false", your site will be asked to supply RETS COMPACT format. This package
does not support RETS STANDARD_XML format yet.
- TRANSLATE_DESCRIPTIONS - If the server you are using a) supports
RETS Standard metadata and b) produces well formed XML, you should set this
value to "true". When set to "true", the descriptions of the data elements
will automatically be translated to a longer, consumer-friendly form. If you
set this value value to "false", the descriptions of the fields will not be
translated to their long description format. The default is "true".
- PAGINATION - Some servers do not support enough of the RETS standard
to allow query results to be packaged into pages for easier viewing.
|
|
|
Refresh Metadata
The package keeps a copy of the metadata (information about the fields) for
the server locally as a performace enhancement. The RETS specification
encourages this practice.
When a Source is created, a copy of the metadata is taken. The
server operator may change the metadata in the future. You can grab a new
copy of the metadata with this option.
|
|
|
High Volume Streaming
This section contains parameters that you might find useful if you anticipate
processing thousands of rows or if you are continually running out of memory.
If neither of these conditions is not present, you should leave these settings
at their default setting which leave streaming turned off. If you use this
capability, "pagination" will not be possible.
- STREAM_PROCESSING - Specify whether you would like to perform
"on-the-fly" rendering of the listings. Set this to "true" if you anticipate
processing result sets with thousands of listings. If you plan to use this
project as the basis for an application that does something other than
creating HTML pages, you might find it handy to set this to "true". If you
run out of memory while processing records, you should set this to "true".
This is a new setting as of Version 2.0. Defaults to "false".
- SIMULTANEOUS_LOGINS - This setting is only relavent if you set
STREAM_PROCESSING to "true". To accomplish streaming, this package needs to
either issue an embedded session or a concurrent transaction. Embedded
sessions require that the server support more than one session with the same
login. Many older RETS Servers support this, but for security reasons, some
newer RETS Servers do not. The reason that the newer servers do not support
multiple session with the same login is to discourage the practice of
"sharing logins". This practice is looked down upon in all security circles.
Setting this parameter to "true" allows older, less secure RETS Servers to
perform streaming. If you require streaming, you should try to work with
servers that support "simultaneous sessions". This is a new setting as of
Version 2.0. Defaults to "false".
|
|
|
Display
This section allows you to display extra information to help you tune the
package for performance. It can also display informatin that will help you
"debug" installations with your MLS. These items were added as of Version 1.1.
- DISPLAY_PERFORMACE - Generates a pair of tables that contain
performance information. One table contains runtime statistics and the other
contains the settings that might affect performance. Defaults to "false".
- DISPLAY_RETS - Generates a table the summarizes all RETS
sent to the RETS Server. These are sorted by transaction type (Login, Search,
GetMetadata, GetObject and Logout). If multiple RETS transactions were
required (as is the case with GetObject for multiple images), each call is
documented. Defaults to "false".
- DISPLAY_PROVIDER_NOTICE - Many RETS servers support the passing of
notices from the MLS to the member as part of RETS. This configuration item
generates a table that displays this notice. Defaults to "false".
- DISPLAY_ACCOUNT - When logging into a RETS server, a summary of
account information is returned. This configuration item generates a table
that displays the account information. This table may help you determine the
correct setting for the
OWNERSHIP_VARIABLE
presented below. Defaults to "false".
|
|
|
Text Query
This section contains settings for text-based listing information. The same
Resource used by
Media Queries
is used by Text Queries. You will need to consult with your service provider
for proper settings. The help key next to each item brings up a
dialog with all possible values. In some cases, the help screen
includes a CLEAR button to set all values to null.
-
OWNERSHIP_VARIABLE
- Used to define which data element is used to
identify the ownership of the record and is usually the agentID field. This
is highly site dependent.
- DETAIL_ITEMS - The items to be returned from a query made for a
detail level display of a listing. These are highly site dependent. This
setting was called SELECTION_ITEMS in Version 1.0.
- GALLERY_ITEMS - The items to be returned from a query made for a
gallery level display of a listing. These are highly site dependent. This
setting is new to Version 1.1.
- SUMMARY_ITEMS - The items to be returned from a query made for a
summary level display of a listing. These are highly site dependent. This
setting is new to Version 1.1.
- QUERY_ITEMS - The items to be shown on a form that enables queries.
These are highly site dependent. This setting is new to Version 1.1.
- STANDARD_SERVER_RESPONSE - Some servers that claim to be RETS
compliant actually produce non-standard XML data. Their responses are not
well formed and cannot be parsed with standard XML parsers as the RETS
Standard intended. If you are trying to configure one of these sources,
set this to "false". This setting is new to Version 2.0. The default is
"true".
|
|
|
Search Forms
This section contains settings for forms-based prompts for the consumer.
You will need some knowledge or the RETS DMQL specifcation language if you want
to define complex prompts. There is a built-in governor that will only allow
a maximum of 99 listings to be returned. This feature eases the burden on RETS
servers for "wide open" searches.
The distribution has an example of defining forms. The definition looks like
this:
<![CDATA[define("QUERY_ITEMS","ListingID,ListPrice,StreetName,PostalCode");]]>
In this case, a form with four fields would be generated. Without further
definition, each of these fields would be generated as a text entry that
need to match exactly with the values on the RETS Server. For example, if
the consumer entered the field for "StreetName"as "Main Street", only listings
on that street would be returned.
This functionality is so basic and most searches conducted by the consumer
are actually performed as ranges. I will now discuss how to specify ranges.
At the bottom of the definition file, arrays are defined for this purpose.
An example would be:
<![CDATA[$ListPrice_FORM=array("Less than $150,0000"=>"150000-",
"Between $150,000 and $200,000"=>"150000-200000",
"Greater than $200,000"=>"200000+");
]]>
This means that the "ListPrice" ($ListPrice_FORM) field has three options:
- Less than $150,000
- Between $150,000 and $200,000
- Greater than $200,000
If there is a statement that looked like this:
<![CDATA[$ListingStatus_FORM=array("VISIBLE"=>"A");
]]>
It specifies that the query should set the defualt for "ListStatus"
($ListStatus_FORM) to "A". The key work "VISIBLE" allows the field to
be displayed to the consumer. If you set this to any other value, like
"DEFAULT", the option will not appear to the consumer.
You must be sure that the definitions refer to elements that are part of
the "QUERY_ITEMS" definition.
|
|
|
Media
This section defines the media characteristics of the RETS server you are
connecting to. The RETS specification requires a Resource to be used when
requesting media. The same Resource used by
Text Queries
is used by Media Queries. You will need to consult with your service provider
for proper settings. The help key next to each item brings up a
dialog with all possible values.
- MEDIA_TYPE - The type of media to be displayed in the media table.
The RETS specification identifies some common values for this field. Defaults
to "Photo".
- MEDIA_MULTIPART - If the server supports the RETS multi-part option,
set this value to "true". When set to true, a single request to the server
returns all information about the images for a property. This setting is
highly site dependent and only relevant if the MEDIA_LOCATION parameter is set
to "true". Defaults to "true".
- MEDIA_LOCATION
- If the server supports the RETS Location option,
set this value "true". When set to "true", the location from the RETS server
is assumed to be a direct URL to the media. When set to "false", a proxy
specified by the
RETS_MEDIA_PROXY
setting is used to serve the image to the browser. Defaults to "true".
- MEDIA_LIST_ZERO_START - If the server starts counting images at one,
set this value to "true". This setting is only relevant if either the
MEDIA_MULTIPART or MEDIA_LOCATION parameters (see above) are set to "false".
If the server starts counting images at zero, set this value to "false".
Defaults to "false".
- MEDIA_VALIDATE - This setting will validate if media actually exists
on the server BEFORE the page is rendered by the browser. It will slow down
page generation significantly because images will be requested twice. If your
server has many missing images, it may be helpful to turn this to "true". On
the other hand, if your MLS has a pretty good fill of images, you might want to
turn this to "false". Defaults to "false".
- MEDIA_PROXY - This setting controls the handling of RETS Servers that
do not support the Location option of the RETS GetObject transaction. In these
cases, a "proxy" is supplied with the distribution to take advantage of
multi-threading in the browser. This proxy is located withing the distribution
by default. If you would like to move it to another location, you should
specify the "web" address to use here. Do not use the location of the
directory. You should also use the script found in the
extras directory
called "movable_media_proxy.php" as a sample of the proxy. You will need to
modify this file to point at this distribution.
|
|
|
|
|
