= Nwmls
An object mapper for the Evernet NWMLS Soap Web Service
== Supported versions
Put this line in your Gemfile: gem 'nwmls', :git => "git@github.com:luxre/nwmls.git"
Then bundle: % bundle
=== Configuration Set your Evernet credentials by creatinge an initializer in your rails app. You can use the generator or your text editor.
% ./bin/rails generate nwmls USER_ID PASSWORD SCHEMA_NAME
You can omit the arguments for the generator and set the values in the initializer later The default initializer will be generated at config/initializers/nwmls.rb with the following content
Nwmls.configure do |config| config.user = <%= ENV['NWMLS_USER'] %> config.pass = <%= ENV['NWMLS_PASSWORD'] %> config.schema_name = 'StandardXML1_5' end
Remember to add the initialize to you .gitignore if you're storing your password directly in the file.
In this intializer you can also set the SchemaName for your query results using the schema_name setting. The default is StandardXML1_5.
== Usage
=== Finding a batch of listings
The Nwmls::Listing.find method will return an array of Nwmls::Listing objects if given a hash. The possible keys for that hash are: :property_type :status :county :area :city :begin_date :end_date :office_mls_id :agent_mls_id :bedrooms :bathrooms
e.g. Nwmls::Listing.find(:property_type => "RESI", :status => "A", :city => "Seattle")
The options for :property_type are "RESI", "COND", "BUSO", "COMI", "FARM", "MANU", "MULT", "RENT", "VACL". If the :property_type key is not supplied then "RESI" is the default
There are subclasses of Nwmls::Listing based on the property types. Your result objects are returned as instances of these classes. You can also use find with these classes, for example Nwmls::Listing.find(:property_type => "COND")
is equivalent to Nwmls::CondominiumListing.find()
The supported subclasses are Nwmls::ResidentialListing #RESI Nwmls::CondominiumListing #COND Nwmls::BusinessOpportunityListing #BUSO Nwmls::CommercialListing #COMI Nwmls::FarmListing #FARM Nwmls::ManufacturedHomeListing #MANU Nwmls::MultiFamilyListing #MULT Nwmls::RentalListing #RENT Nwmls::VacantLandListing #VACL
=== Finding a single listing by its listing number If you give find the key :listing_number then a single result will be returned instead of an array. Example: Nwmls::Listing.find(:listing_number => '454186') Conveniently, you can also find a single listing with: Nwmls::Listing.find(454186)
=== Raw Attribute Mode If you add the following to your config/initializers/nwmls.rb initializer file: Nwmls::Model.attribute_mode = :raw
The model will act in "raw" mode. This means that attribute's names and values will be returned exactly as they are represented in the Evernet schema. For example, Nwmls::Listing objects will have attribute LN instead of listing_number. Values for boolean attributes are returned as strings "1" and "0". Attributes that return arrays will return | delimited strings.
== Images === Image Data You can get image data for a listing with Nwmls::ImageData.find(:listing_number => listing_number) This will return a collection of Nwmls::ImageData objects with methods: ml_number, picture_file_name, picture_height, picture_width, picture_description, uploaded_date_time, and last_modified_date_time. You can use this data to fetch an image file the NWMLS ftp server or use it with Nwmls::Image
=== Images Nwmls::Image wraps the Nwmls Image Service. You can use it to get information, including the binary data, for images. To get all the images for a listing Nwmls::Image.find(:listing_number => listing_number) An image by sequence (1 to 15) Nwmls::Image.find(:listing_number => listing_number, :sequence => n) An image by name (use picture_file_name from Nwmls::ImageData results) Nwmls::Image.find(:name => picture_file_name) You can write the above without the name option Nwmls::Image.find(picture_file_name) When the sequence or name options are given a single object is returned. When only the listing_number is provided an array of objects in returned.
An Nwmls::Image instance has the methods: image_id, image_order, upload_dt, and blob
=== Rendering with Rails The blob method on an Nwmls::Image object is the raw data for the image file base 64 encoded. An example action that would render the image inline might look like this
def show | @image = Nwmls::Image.find("#{params[:id]}.jpg") | respond_to do |format| | format.jpg {· | if @image.nil? | head :not_found | else | send_data(Base64.decode64(@image.blob), :type => "image/jpeg", :disposition => "inline", buffer_size: '4096') | end } end end
== Open Houses To get all open houses use Nwmls::OpenHouse.find
The method accepts parameters but they are ignored. All open houses in the system are returned even if you give :listing_number, :start_date, and :end_date parameters. An Nwmls::OpenHouse object has the methods id, modified_dt, :listing_number, :start_dt, :end_dt, and description