IDX Smart Framing Application

Integration Support Page

Contents

The Basics

Integrating the IDX Application with a Web Site

Framing

Base Account Information

Profile Configuration Information

Token Security

Token Expiration

Example Token Retrieval Scripts

   - ASP Example

   - Perl Example

Obtaining Your 'Home Server' IP

Downloads (Documentation and Scripts)

The Basics

This page provides information on how to integrate the MarketLinx IDX Smart Framing Application into a participating web site.

What is the IDX Smart Framing Application?

The IDX Smart Framing Application consists of a set of web pages that provide for the search and display of the property listings provided by participants in the MLS IDX program.

Who can frame the IDX Smart Framing Application into their site?

Eligible sites are those belonging to member brokers who have elected to participate in the IDX program.

How is the IDX Smart Framing Application framed into a web site?

The IDX Smart Framing pages may be incorporated into the web sites of program participants by including them in framesets hosted on the participants' sites. For users to successfully access the framed IDX Smart Framing pages, a security token must be requested by the framing site on behalf of the user from a special token dispensing web page and passed along in the URL of the initial Smart Framing web page. This must be performed by a script or program running on the server of the framing site. A detailed discussion of this token security system is included in the Token Security section below and in the  IDX Smart Framing Application Program Guide, which is available for download from this page.

Integrating the IDX Application with a Web Site

Integrating the IDX Smart Framing Application with a web site is relatively simple. For the most part, you can treat the IDX Smart Framing Application as a set of web pages running on another server that you will include in a frameset file on your server. If the site into which you are incorporating the IDX application already uses frames, you can even use the existing framesets.

There are, however, a number of issues with integration that can complicate the process and slow down site development if not handled carefully.

First, there is some information that must be provided to the IDX Program Coordinator for the MLS. This information is used to set up an IDX Smart Framing account, make it ready for framing into a particular site, and configure some options. Providing incomplete or inaccurate account information can cause not only technical difficulties with framing but also administrative headaches.

Second, a script or program must be set up on the framing web site to handle the security tokens required by the IDX Smart Framing Application. The trickiest part of integrating the IDX Smart Framing Application into a web site is working with the token security system employed by the site. However, the scripts are very simple and most developers can simply make minor changes to the example scripts provided.

Framing

To frame the IDX Smart Framing Application, you will display it within an HTML frameset page. The frameset page will divide the browser window into two or more frames, or panels. One frame will contain the IDX Smart Framing Application hosted by the MLS. The other panel(s) will contain pages from the participant’s site including their own logos, links, menus or other content.

The frameset page will be a part of the IDX program participant’s own web site. It will reside with the rest of the pages that make up the site and should be prepared by the subscriber or his/her designated web developer. Likewise, the page(s) surrounding the IDX Smart Framing Application in the frameset will be a part of their own web site and will be the responsibility of the subscriber or designated web developer.

Base Account Information

The following information is required for establishing an IDX Smart Framing account. Most of this information will come from the broker or agent participating in the IDX program, but some (such as the Home Server, and Framing URL values) may have to be provided by you, as the web developer, or the service hosting the site. If you are coordinating directly with the IDX Program Coordinator at the MLS organization, it may be convenient for you to collect this information from the broker or agent you are working for and have it ready to present to the MLS IDX Program Coordinator.

Display Name – This is the name of the firm, broker or agent that will appear in the footer of every page, at the top of the printable reports, and possibly other places throughout the application.

Display Phone – This is the phone number of the firm, broker or agent that will appear in the footer of every page, at the top of the printable reports, and possibly other places throughout the application.

Display E-mail – This is the e-mail address of the firm, broker or agent that will appear in the footer of every page, at the top of the printable reports, and possibly other places throughout the application. It will generally appear as a ‘mailto’ link, which will usually open the user’s e-mail client when clicked.

Lead E-mail – This is the default e-mail address to which e-mail leads should be sent. (On broker sites, if the agent e-mail option is enabled, leads for internal listings will be sent to the listing agents and all others will go to the “Lead E-mail” address.)

Framing URL – This is the complete URL of the frameset that will be framing the IDX Framing Pages. It should begin with ‘http://’. This information is collected for review of your site and to help resolve any problems that may arise with your framing implementation.

Token Expired Page – In the event that a user discontinues use of the IDX Framing Pages for a while and then resumes usage, they will be provided with a link to restart their user session. This link is usually the same as the Framing URL above. However, you may choose to send users to another page, such as your site’s home page, when their session has expired.

Home Server – This is the IP address of the server on which the site is hosted. If you use more than one IP address for your web site (as with load-balanced sites) you must supply all IP addresses from which token requests will be made. If your site resides behind a firewall server that translates the IP Address of outgoing requests (this is usually the case with commercial hosting services), you may have to supply the IP address of the firewall server(s). The value submitted for the Home Server must be the address of the server from which the token request will appear to have originated.

If you are using a commercial hosting service, it is very common for the IP in the outgoing “REMOTE_ADDR” request header to be different than that of the server on which your web site is hosted. Often this is a very unexpected value. Please see “Determining Your ‘Home Server’ IP” later in this document for tips on how to obtain the correct value.

Logo File – For internal listings (listings of your own broker or firm), this file will replace the standard logo representing IDX listings from other brokers.

Office IDs for Property Matching – Several features of the IDX Smart Framing application behave differently when displaying listings owned by the framing broker than they do for the rest of the listings. To determine which properties should be considered "internal" (owned by the broker with which the framing site is associated) the application must know which Office IDs are to be associated with the smart framing profile. This value should include all of the Office IDs that are associated with the MLS data records of properties that should be considered "internal" properties for the profile. This would, for example, include the Office IDs for all offices of a single broker firm that control their own listing data.

Profile Configuration Information

For each site that frames the IDX Smart Framing Application there is a set of configurable parameters, or “profile’, that can tailor the appearance and functionality of the application for the framing site. In many cases the web developer is called upon to help provide the information required for this configuration. For those systems that have web-based administrative tools accessible to program participants, designated developers may be asked to configure the site directly using the administrative tools.

The following profile characteristics are available on most IDX Smart Framing Applications.

Appearance Information:

At a minimum, you should be able to specify the following color values, either through your admin interface, or through your IDX coordinator. These can be specified as general color names (green, gray, yellow, light-blue), or they can be provided as standard hex code color specifications (#AADD44, #6699BB). You may be able to control or specify other visual characteristics depending on your particular system and MLS policies.

Page Background Color – The overall color of the IDX Framing Pages.

Table Background Color – The overall color of tables throughout the IDX Framing Pages.

Table Border Thickness – The thickness in pixels of the outer border of  tables used throughout the application. This value can be set to '0' to remove the borders.

Table Border Type – The style of the outer border of tables used throughout the application. Valid values are: solid, double, groove, ridge, inset and outset.

Table Border Color – The color of the outer border of tables used throughout the application.

Table Cell Text Color – The color of the plain text appearing in tables throughout the application.

Table Cell Border Thickness – The thickness of the border surrounding the non-heading cells of tables appearing throughout the application. This value can be set to '0' to remove the borders surrounding the table cells.

Table Cell Border Type – The style of the border surrounding the non-heading cells of tables appearing throughout the application. Valid values are: solid, double, groove, ridge, inset and outset.

Table Cell Border Color – The color of the borders surrounding non-heading cells of tables appearing throughout the application.

Table Cell Link Color – The color of hyperlink text appearing in tables throughout the application.

Table Cell Hover Color – The color of hyperlink text appearing in tables throughout the application when a user places the cursor over the text.

Table Cell Active Color – The color of hyperlink text appearing in tables throughout the application when a user has clicked the link text.

Table Cell Visited Color – The color of hyperlink text appearing in tables throughout the application when a user has previously visited the link.

Table Head Cell Background Color – The color of heading cells within the tables.

Table Head Cell Text Color – The color of the plain text appearing in heading cells of tables throughout the application.

Table Head Cell Border Thickness – The thickness of the border surrounding the heading cells of tables appearing throughout the application. This value can be set to '0' to remove the borders surrounding the table cells.

Table Head Cell Border Type – The style of the border surrounding the heading cells of tables appearing throughout the application. Valid values are: solid, double, groove, ridge, inset and outset.

Table Head Cell Border Color – The color of the borders surrounding heading cells of tables appearing throughout the application.

Table Head Cell Link Color – The color of hyperlink text appearing in heading cells of tables throughout the application.

Table Head Cell Hover Color – The color of hyperlink text appearing in heading cells of tables throughout the application when a user places the cursor over the text.

Table Head Cell Active Color – The color of hyperlink text appearing in heading cells of tables throughout the application when a user has clicked the link text.

Table Head Cell Visited Color – The color of hyperlink text appearing in heading cells of tables throughout the application when a user has previously visited the link.

Field Label Text Color – The color of field labels and other emphasized text appearing in tables throughout the application.

Main Menu Background Color – The color of the top menu bar of the application.

Main Menu Text Color – The color of the text appearing in the main menu of the application.

Navigation Menu Background Color – The color of the navigation menu (second menu bar from top) on each page.

Navigation Menu Text Color – The color of the text appearing in the navigation menu (second menu bar from top) on each page.

Action Menu Background Color – The color of the action menu (third menu bar from top) on each page.

Action Menu Button Color – The color of the buttons on the action menu (third menu bar from top) and other places where the action menu button style may be used in the application.

Action Menu Button Text Color – The color of the text on the buttons of the action menu (third menu bar from top) and other places where the action menu button style may be used in the application.

Message Text Color – The color of text content generally appearing outside of tables throughout the application, such as in login prompts, error messages, disclaimers, and page footers. These messages generally appear against the page background, so the chosen Message Text Color should contrast with the selected Page Background Color for best readability.

Message Text Size – The size of text content generally appearing outside of tables throughout the application, such as login prompts, error messages, and page footers (but not disclaimers).

Functional Information:

In addition to the appearance configuration settings, some systems will permit subscribers to configure functional characteristics of the application. As with the appearance settings, some systems will offer subscribers direct control of these settings through a web-based administrative system while others will configure the settings on behalf of the program members.

Common configurable functional parameters for the IDX Smart Framing Application include the following:

Allowed Property Types - This setting allows subscribers to specify which property types (residential, commercial, etc.) will be supported by their site. Some subscribers may even wish to create multiple profiles supporting different sets of property types for framing into different sites. This allows participants to have separate sites for residential and commercial properties, for example.

Allowed List Prices - This setting allows program participants to configure their sites to search and display only properties with list prices in a specific range.

Allowed Areas - This setting allows program participants to configure their sites to search and display only properties in certain geographic areas.

Login Required for Search - This setting allows program participants to require users to register with the site before they can use the property search features. Registration involves establishing an account with the site, selecting a password, and providing some basic information about themselves.

Internal Listings Display Agent Info - This setting allows brokers to specify whether information about the listing agent is displayed for listings associated with his/her own firm.

E-mail Leads for Internal Listings go to Agent - This setting allows brokers to specify whether e-mail leads regarding listings associated with his/her own firm go to the listing agents or the profile’s default e-mail address.

Display Address - Available for some IDX systems, this setting allows program participants to determine whether the listing data displayed on their sites will include property street addresses.

Token Security

Although requiring relatively little programming, interfacing with the security features of the IDX Smart Framing Application is the most complex part of implementation.

To ensure that users can access the IDX Smart Framing Application only through authorized web sites, sites that frame the pages are required to request a security token on behalf of each user of the IDX Smart Framing pages. This token is like an admission ticket that is given to each user so they may access the features of the IDX application. Each user will receive a different token.

This token must be requested by a script or program running on the server (computer) hosting the site that is framing the IDX pages. Note that this is a server to server transaction in which the end user’s browser is not involved.

Because so many different types of web server environment will be used to interface with the IDX system, the scripts or programs used to retrieve the token must be the responsibility of the owners and/or developers of the sites that make use of the IDX system. Each different type of web hosting environment supports a different set of server scripts and programs. For example, if you host your web site on Windows 2000, you will probably want to use ASP script for token requests. If your site is hosted with a commercial hosting service, such as Earthlink, your provider may limit your use of server-side programs to Perl script or compiled CGI programs. Further, CGI programs generally need to be compiled for the particular operating system on which they will run, such as Solaris, AIX, Linux, and so on. Check with your web hosting provider or web developer to find out which server scripts and programs are supported for use with your web site.

Some example scripts are provided to simplify interfacing with the token server. In many cases, these scripts can be easily modified for your use. ASP and Perl script examples are discussed later in this document for those hosting their sites on Microsoft Windows NT/2000/XP or a platform supporting Perl. Other examples will be provided here as they become available.

If you develop a script for your platform and you would like to share it with other users of MarketLinx IDX solutions around the country, please give it to the IDX Program Coordinator at the MLS. If you would like use of your script limited to developers outside of your area, please let your coordinator know.

The token is requested using a standard HTTP request, just as your browser makes to obtain web pages. The token is generated and returned by a special token generation web page hosted by the MLS. Only requests from authorized servers will be honored.

Note: The IP address of the requesting server is retrieved from the token request and matched against the value stored in our database as your “Home Server.” All token requests for your web site must originate at your Home Server. If you use more than one IP address for your web site (as with load-balanced sites) you must supply all IP addresses from which token requests will be made. If outgoing requests from your site are made through a proxy server, you must supply the IP address from which the token will appear to have originated (i.e., the proxy server IP).

The web address for the token page is available from your IDX coordinator. It is also included in the script examples provided for download from this page. The unique Profile ID provided with each account will need to be appended to the token request as follows:

http://www.servername.com/tokeninit.asp?pid=231

An example of how to make a token request is discussed later in this document.

The token will be returned in an HTTP response, just as a web page. The token is a long string of alphanumeric characters. This string holds several pieces of encrypted information used by the IDX Smart Framing Application.

Once a requesting server receives a token, it will add it to the URL of the Main IDX search page as a request parameter. The URL should look similar to the following:

http://www.servername.com/templates/search_form.asp?sec=OE2FF4GJK90DSVM…

        (The long string of characters following the “?sec=” is the encrypted security token received from the token server.)

Dynamic Frameset Script

The URL to the initial Smart Framing page with the appended token can be used within a dynamically generated frameset as the source of the frame containing the IDX Smart Framing Application. This is the preferred integration method.

1. The user clicks a link on your site requesting the frameset file.

2. A script executes on your server, which retrieves a token from the IDX server and constructs a frameset with the token appended to the URL of the framed IDX page.

3. The Frameset containing the token is sent to the user.

4. The user continues to interact with the IDX Framing Pages server passing the token in each request.

Redirect Script

If necessary, a script or CGI program can be designated as the source of the frame. That script or program can make the request to retrieve the security token and redirect to the IDX Framing Page. This method is less desirable in that the URL of the script or program itself could be framed by unauthorized parties, although some additional protections are in place to prevent this.

1. The user clicks a link on your site requesting the frameset file.

2. The static frameset file is returned. The “src” attribute of the IDX frame contains the URL of a script on your server.

3. The request for the script is made to fill the IDX frame of the frameset.

4. The script executes on your server, retrieving a token from the IDX server.

5. The script redirects to the initial IDX page, passing the token in the redirect URL.

6. The initial search page is sent to the user.

7. The user continues to interact with the IDX Framing Pages server passing the token in each request.

Token Expiration

After obtaining a token from your site, a user may continue to use the IDX features. Each IDX web page will check the user’s token for validity and reissue a token for the next request. All tokens will have an expiration time determined by the MLS. Because tokens are reissued with each request, users will typically not experience token expiration unless they leave their browser for some time. Should a user’s token expire, they will be provided with a link to obtain a new one from your authorized framing site. Tokens will immediately be discarded when users quit their web browsers.

Example Token Retrieval Scripts

ASP (Microsoft Windows NT/2000/XP)

This simple script example demonstrates how to obtain and use a security token from the IDX Framing Pages token server.

This example makes use of a component supplied by Microsoft in its XML software development kit (SDK). This component, “ServerXMLHTTP”, enables server-side scripts and programs to make HTTP requests, much as a browser would. If you are using Microsoft Windows 2000 or XP as your web server platform, chances are fairly good that this component is already installed on your server. There are several other commercial components that can be used in much the same way.

This script actually builds the frameset file (rather than a page within one of the frames). It retrieves a token at the top of the page and stores it in a variable (RecdToken), then it appends to the token to the URL of the IDX Framing Pages search form as the “src” attribute of the lower frame.

This script is available for download in the download section of this page.

To use this script, you would verify the URLs of the token page and initial IDX search page and replace the ‘[ProfileID]’ text with the profile ID supplied by your MLS IDX Program Coordinator. Then you would modify the frameset HTML at the end of the script to suit the needs of your site. Any frameset configuration that properly displays the IDX Smart Framing Application pages will work.

<%

Response.Buffer = True

‘Create an instance of the ServerXMLHTTP class to make the token request

Dim Requester

Set Requester = Server.CreateObject("MSXML2.ServerXMLHTTP")

‘The URL for the token request. Note the “pid=” parameter.

‘Use the Profile ID supplied to you by your IDX coordinator.

Dim DispenserURL

DispenserURL = “http://idxweb1.gsmls.marketlinx.com/TokenInit.asp?pid=[ProfileID]”

‘Open and send the request. Use the ID and Password supplied to you.

Requester.Open "Get", DispenserURL, False

Requester.Send

‘This loop allows some time for a response.

While NOT Requester.readyState = 4

Requester.waitForResponse(1000)

Wend

‘Sets a variable to the output of the token page.

RecdToken = Requester.responseText

‘Cleans up the Requester object.

Set Requester = Nothing

%>

<html>

<head>

<title>Sample Client 1 Frameset</title>

</head>

<%

‘The token page returns a –1 error if a request is invalid.

‘This HTML text provides a message in case a token can’t be retrieved.

If RecdToken = "-1" Then

%>

<body topmargin="0" leftmargin="0">

<h1>Error</h1>

<p>There is a temporary problem with the search features of this site. Please try again later or contact us at 111-222-3333.</p>

<p>We apologize for this inconvenience.</p>

</body>

</html>

<%

‘If the request is valid, build a standard frameset page.

‘Append the token to the URL of the SRC attribute of the IDX frame.

Else

%>

<frameset rows="64,*" framespacing="0" frameborder="0">

<frame name="header" scrolling="no" noresize target="main" src="Top_Frame.html" marginwidth="0" marginheight="0">

<frame name="main" src="http://idxweb1.gsmls.marketlinx.com/custom/templates/search_1.asp?sec=<%=RecdToken%>" marginwidth="0" marginheight="0" scrolling="auto" noresize>

<noframes>

<body topmargin="0" leftmargin="0">

<p>This page uses frames, but your browser doesn't support them.</p>

</body>

</noframes>

</frameset>

</html>

<%End If%>

Perl (Unix/Linux)

This simple script example demonstrates how to obtain and use a security token from the IDX Framing Pages token server using Perl.

This script makes use of a common package of Perl routines that should probably already be installed on most servers configured for Perl CGI execution.

This script is available for download from the download section of this page..

To use this script, you would verify the URLs of the token page and initial IDX search page and replace the ‘[ProfileID]’ text with the profile ID supplied by your MLS IDX Program Coordinator. Then you would modify the frameset HTML at the end of the script to suit the needs of your site. Any frameset configuration that properly displays the IDX Smart Framing Application pages will work. The ‘src’ parameters of the frameset should be complete URLs (beginning with ‘http://’).

#!/usr/bin/perl –w

#

# This script MUST be placed on the server (or behind the proxy server) that uses

# the IP addresses you provided when signing up to work. You must also set the ID

# number where noted below.

#

# I have tested and gotten this to work on both the i386 linux (Slackware), and

# NT 2000 platforms.

#

# LWP::Simple is a module included in the libwww-perl package, and SHOULD be availabe

# on most servers running perl for CGI scripting purposes.

# The most current ver. of the libwww-perl package as of the writing of this is

# libwww-perl-5.64.tar.gz and is available for dload at http://www.cpan.org

# It can be directly ftp'd from ftp.cpan.org from /pub/CPAN/modules/by-module/LWP/.

# If you need further functionality or would rather write your own interface script,

# you might find the modules IO::Socket and URI, or LWP::UserAgent (the 'full' version of

# LWP::Simple) usefull. These can also be found in the libwww package.

use LWP::Simple;

# You must replace the pid below ('19' in this example) with your ID number that

# you recieved after applying for IDX access.

$token = get("http://idxweb1.gsmls.marketlinx.com/tokeninit.asp?pid=19");

# Everything below between the END_of_HTML block tokens is just basic HTML.

# This can be edited to suit whatever needs you might have. I've included a very

# basic frameset but this can be changed to be as much as it needs to be.

#

# One note here, Perl uses the '\' char to force printing of command characters.

# IE, if you need to actually print out '$money' for instance instead of having this

# script think that $money was variable you would need to type it as '\$money'.

# This shouldn't be an issue, but if you see funny things happen here with HTML code

# keep that in mind. I believe I have had an instance or two where I've had to preceed

# the " char with a backslash. It probably depends on what ver. of Perl that is being used

# on the server side.

print <<END_of_HTML;

Content-type: text/html

<html>

<head>

<title>some title</title>

</head>

<frameset rows="15%,*">

<frame name="header" target="main" src="http://www.yourdomain.com/header.html">

<frame name="main" src="http://idxweb1.gsmls.marketlinx.com/custom/templates/search_1.asp?sec=$token">

</frameset>

</html>

END_of_HTML

Obtaining Your ‘Home Server’ IP

In deploying the IDX Smart Framing Application in several markets around the country, we have discovered that many developers do not know the IP address from which outgoing HTTP requests from their web servers will appear to have originated.

In many cases, the web server is configured behind a firewall for security purposes, and this firewall proxies any outgoing requests so that the request seems to have originated with the firewall.

We have provided some simple tools to help in determining the IP address of the outgoing token requests.

First, on the same website as the token dispensing script there is a test script that will return the IP address of the incoming request that triggers it. It will also return the IP address(es) stored in the database for the specified profile.

The URL of this script is as follows:

http://idxweb1.gsmls.marketlinx.com/tokentest.asp?pid=[ProfileID]

You must replace ‘[ProfileID]’ with the profile ID you were provided by the IDX Program Coordinator. You may call the script directly with a web browser to see how it works, but this will return the IP address of the computer from which you are browsing, which will not be useful for integration with the IDX Smart Framing Application.

To get the IP address from the outgoing HTTP requests of your server, this script must be called by your server. If you have already set up a token request script on your server, you may make some slight alterations to it so that it calls the ‘tokentest.asp’ page rather than the ‘tokeninit.asp’ page. You may also have to alter the script so that it simply displays the results of the request rather than trying to use it as a token.

Example scripts for calling the ‘tokentest.asp’ script are provided for several platforms in the download section of this page. You may download the appropriate script for your platform, change the profile ID used by the script, and execute it on your server with a browser to obtain the value for the ‘Home Server’ field in the profile.

Once this value is set correctly in the database, you should be able to successfully retrieve tokens from the token dispensing web page.

Downloads