Jupix and Vebra Property File Shortcodes

Originally Jupix alone had a Property File option but it now also applies to Vebra API properties.  Property file is an add on product that allows Valuation and Viewing widgets to be added you your site that will directly book these in your backend system checking for availability and giving your customers options on when to book these in.  You will need a subdomain and API key for property file and these are added under the Jupix tab in the WP Property Feed Settings in your WordPress Admin panel.  The default property template will launch the viewing widget when a visitor clicks the Request a Viewing link on the property detail page but you may want to add the widgets elsewhere so we have created two shortcodes to allow you to add them in.

[wppf_propertyfile_valuation class=’btn btn-success’ text=’Value Me’] [wppf_propertyfile_viewing class=’btn btn-success’ text=’Arrange a Viewing’ propertyid=”]

These shortcodes will output a link which is properly formatted to launch the required widget.  The valuation widget can be placed anywhere on your site as it does not depend on a specific property being viewed but obviously the viewing widget may only be used on the property page.

The shortcodes have two options  – class is used to pass through any addition styling css classes that you want added to the link and the text is the text that will be displayed in the link.  The viewing shortcode also has an additional option to pass through a specific propertyid which can be ommitted if the shortcode is used on a property details page (it is picked up automatically)

Oxygen Builder Walkthrough

Oxygen builder is a WordPress plugin that allows you to build entire themes and does away with themes altogether.  I guess if you got this far you probably know that already and want some tips on how to build a property theme that makes use of the properties from WP Property Feed.

Archive Page – Property search and results listing

Probably the most important template you will need it a property search and results listing page.  The good news is that this is relatively simple with Oxygen.  First you need to go to wp-admin > Oxygen > Templates and click the “Add New Template” button to start building your template.  Give you template a name (I suggest “Properties”) and then click on “Archive” in the “Where does this template apply?” section.  In the options here tick the “Post Types” option and select “wppf_property” from the dropdown

 

Now you can “Publish” that template which will then reload the page with the “Edit with Oxygen” option available – click that and lets edit the template!

There are two key elements we suggest you use for building your search and results page, a search form and a results grid.  For the search form we are going to use our wppf_quicksearch shortcode, so click “Add” and find the “Shortcode” option and add that to your template.

In the shortcode options add the [wppf_quicksearch] shortcode and you will see the quicksearch form appear.

NOTE: To style the quicksearch shortcode layout we suggest you use css to override our base styles, you can also edit the layout of the quicksearch by editing the underlying template – see our Templates documentation for more details.

Okay so we have a search form, now we need a results section below to display the matching properties.  For this we will add a “Repeater” element (in the Helpers section).  Once added to your template you do not need to change the “Query” section as by default the results will be controlled by our search and results logic, but feel free to change any of the layout and pagination options.  Finally we need to add our property content to the template in whichever layout you determine.

In the repeater we would suggest that you add the Post featured image (main property image), Post Title (name of the property) and Post Excerpt (brief description of the property).  You can then add any of the property attributes which are stored as Post meta data.  In most cases when you add or edit an element there is an option to “Insert Data”

Which is turn gives you the options to select the type of data

and finally if we are after specific property attributes we can select the attribute from the dropdown options

Using the “Insert Dynamic Data” we can pick out all the property features you may want for the results template.

Once you have your template complete you can view the search and results page by going to the standard wppf_property archive page https://www.yoursite.com/property (obviously change www.yoursite.com to the address of your site!).

Property Page

So to complete the search and results listing we need a single page for the property details.  So return to the wp-admin and Oxygen > Templates and “Add New Template”.  For this walkthrough I am calling my template “Property” and selecting the “Singular” from “Where does this template apply?” and selecting “Properties” so that this template only applied to property post types.  After publishing the template you can then “Edit with Oxygen” and as with the repeater on the archive page you can add Titles, text and meta data using the various Oxygen elements and “Insert Dynamic Data” options in those elements.

Picture Gallery, Floorplans and EPCs

There is one special case where we need to Oxygen a little help to pick up the correct data and that is to get the picture gallery, floorplans and EPCs.  We want all these images to be available to the gallery element in Oxygen and to do that follow these steps.

On your template add a “Gallery” element.   You will be presented with the options with seemingly no way of selecting the property picture gallery, floorplans or EPCs as the only “Gallery Source” options are “Media Library”, “ACF” and “WooCommerce” with no option to select “Insert Dynamic Data” (hopefully this will change in future Oxygen versions).  So in order to work around this issue we have added some filters that look for specific “Image IDs” text.  So to use the property pictures leave the “Gallery Source” unselected or select “Media Library” and then in the Image IDs enter either “pictures”, “floorplans” or “epcs” and this will immediately populate the gallery with the relevant images.

Once you have designed and completed your property template you will have a fully functioning property search and and results in place using all the data supplied via our WP Property Feed plugin.

Extras

Search Result Map.

If you want to display a map on your property results page with all the searched properties pinned to the map you will first need to add a code block to your property archive template at the top of the page with the following code;

<?php wppf_map_pins();?>

This primes the plugin with all the javascript property data needed by our plugin to populate the map.  Then on the same template add a div element making sure it’s id is wppf_map and set an appropriate width and height.  You will not see the map in the preview view but on the live results page the div placeholder will be replaced by a map with properties pinned to it.

Paragraphs, Documents and Branch Details

On the single property template there are extra post meta datafields that require a code block to display because they contain array data (rather than single values).  In all the examples below we have just echo’d out the basic data, you will want to amend the code to add in html formatting of the results.

Paragraphs

Paragraphs contain room names, dimensions and text so can be import additions to the overall descirption.  Use the following code to display the paragraphs

<?php
$paragraphs = wppf_get_paragraphs(get_the_ID());
foreach ($paragraphs as $paragraph) {
echo $paragraph[‘name’]; //room name
echo $paragraph[‘dimensions]; //room dimensions
echo $paragraph[‘description’];
} ?>

Documents

Usually there is just one document – the full details as a PDF but there may be more than one so this is another array element that needs adding as a code block like so;

<?php
$docs = wppf_get_documents(get_the_ID());
foreach($docs as $doc) {
echo $doc[‘url’];  //the url of the document
echo $doc[‘name’]; //name of the document
} ?>

Branch Details

Branch details is a taxonomy but as we add branch contact details to this taxonomy you will need a code block to extract the details as follows;

<?php
$branch = wppf_get_branch(get_the_ID());
echo $branch->name;
echo wppf_get_branch_address($branch->term_id, “<br>”);
echo get_term_meta($branch->term_id,’phone’, true);
echo get_term_meta($branch->term_id,’email’, true);
?>

We hope this was helpful!

Getting Started

STEP 1 – INSTALL THE PLUGIN

Once you have downloaded you WP Property Feed plugin zip file you can install in one of two ways;

  1. In WordPress admin go to the plugins section and click “Add New” then click on the “Upload Plugin” option and select the wp-property-feed.zip you just downloaded and click “Install Now”.  Once installed click the “Activate” button to make the plugin available.
  2. Extract the wp-property-feed.zip you just downloaded on your computer and using ftp upload the content to you wordpress site in the wp-content/plugins directory.  Then log into wordpress admin and go to plugins where you should now see WordPress Property Feed listed.  Click the activate link and the plugin will then be available.

STEP 2 – ENTER YOUR PLUGIN LICENCE KEY AND OTHER PLUGIN SETTINGS

In the wordpress admin dashboard select the “Settings” > “WP Property Feed” menu. Enter your license key into the top box and click “Save Changes” at the bottom of the page.  Once updated you will see the license status on right of the page showing the plugin is active.  To make the search and mapping work correctly it is also important to enter a google maps api key which can be obtained for free from https://developers.google.com/maps/documentation/javascript/get-api-key  Please note, do not add any domain restrictions to you google maps api key as that will prevent the radius search from working.

STEP 3 – ENTER YOUR FEED DETAILS AND PERFORM YOUR FIRST IMPORT

The details you will require will depend on the feed you are planning to integrate into your wordpress site.  There are separate tabs for each of the feeds, just select the relevant feed, or feeds and enter the API details you have been given.  If you don’t have any details yet then contact your software provider (Vebra, Alto, Jupix, etc) and they will be able to provide the details you need.

You will notice that on all of the feed pages there is a “Force Refresh” option to refresh the entire property list, tick this box and click the “Save Changes” button.  This update will sometimes take a while so please be patient but once completed you will have your properties available on your site.

STEP 4 – VIEW YOUR PROPERTIES

Viewing your properties is simple, just go to /property/ page on your site (e.g. http://www.yoursite.co.uk/property/).  You can also use the tags /property_area/to-buy/, /property_area/to-rent/ to see just the sales or rental properties respectively.  Click here for the full set of url options available.

STEP 5 (OPTIONAL) – ADD SHORTCODES

Finally you can spruce up your site by adding in shortcodes to the pages of you site.  There are codes for search panels, sliders, featured properties and maps.  Click here for full details of the shortcode options.

STEP 6 (OPTIONAL) – CUSTOMISE

There are plenty of options for you to play with in the plugin itself and for more advanced users the full set of templates are available to fully customise the layout of all elements of the plugin, Click here for more details.  Of course you can always contact us if you need help and/or advice on customising the plugin templates OR to find out more about our customisation services.

Property Feed Url Structure

The plugin imports properties into wordpress as a custom post type which means that you can quickly see all properties via the post type archive and single pages.  We have used the slug ‘property’ so you the links are;

  • /property/ – archive page showing the full list of properties
  • /property/{a-specific-property}/ – shows a single property.  The {a-specific-property} part will be a specific auto-generated url for each particular property.

On top of the standard /property/ archive there are specific archives for property areas, property types and branches as follows;

  • /property_area/{property area}/ – where {property area} is one of to-rent, to-buy, commercial or developments
  • /property_type/{property type}/ – where {property type} is any valid property type – e.g. house, flat, bungalow, etc
  • /branch/{branch}/ – where {branch} is the branch slug.

Widgets

We provide you with one simple widget “Property Search” that you can insert into any widget area you like.  This is a simple location/property type (Sale/Rent) search box.  If needs be this can be customised by editing the wppf_layout_widgetsearch.php template (see Templates) but it will just work straight out of the box.

Shortcodes

This plugin has fleixble short codes to allow you to drop specific wppf functionality onto any page within your site.

  • wppf_quicksearch – by default this is horizontally formatted search bar with search by location, search type (buy/let/commercial), min/max price and bedrooms
  • wppf_search – a more detailed search formatted to view vertically that includes many more search options
  • wppf_featured – short code to display a selection of properties (using shortcode options to filter)
  • wppf_slider – shortcode to display a full width slider of selected properties (using shortcode options to filter)

To add options simple include them in the shortcode as a name value pair e.g. [wppf_search branchid=”1″ type=”To Buy”]. See below for the full set of options available for each short code. Only add attributes to the shortcode if you want to pre-filter results. Any manually entered search criteria will override the attributes set in the shortcode.

[wppf_quicksearch] and [wppf_search]

  • wppf_branch (branch number)
  • wppf_search (comma separated list of; to-buy, to-rent, commercial)
  • wppf_location (a string containing the location i.e. Leicester, UK)
  • wppf_featured (yes)
  • wppf_min_bedrooms (number value)
  • wppf_max_bedrooms (number value)
  • wppf_min_price(number value)
  • wppf_max_price (number value)
  • wppf_min_rent (number value)
  • wppf_max_rent (number value)
  • wppf_min_area (number value)
  • wppf_max_area (number value)
  • wppf_property_type (comma separated list of property types)
  • wppf_status (comma separated list of status)
  • wppf_user1 (comma separeted list of user1 field values)
  • wppf_newbuild (yes)
  • wppf_lettype (comma separated list of let types)
  • wppf_furnished (comma separated list of the following options – Furnished, Un-Furnished, Part-Furnished, Not Specified)
  • wppf_soldlet (hide or show – hide will hide an properties that are sold, let, let agreed, sstc – show will show all properties including sold and let)
  • wppf_orderby (can be price-asc, price-desc or latest, default is price desc unless search be location then default is nearest)
  • wppf_radius (distance in miles from the location center for location searches only – default is 10 miles),
  • wppf_records (number of records to return per page)

Quick Search

Search

[wppf_featured] and [wppf_slider]

  • wppf_branch (branch number)
  • wppf_slug (comma separated list of property slugs)
  • wppf_search (comma separated list of; to-buy, to-rent, commercial)
  • wppf_featured (yes)
  • wppf_min_bedrooms (number value)
  • wppf_max_bedrooms (number value)
  • wppf_min_price(number value)
  • wppf_max_price (number value)
  • wppf_min_rent (number value)
  • wppf_max_rent (number value)
  • wppf_min_area (number value)
  • wppf_max_area (number value)
  • wppf_property_type (comma separated list of property types)
  • wppf_status (comma separated list of status)
  • wppf_user1 (comma separeted list of user1 field values)
  • wppf_newbuild (yes)
  • wppf_lettype (comma separated list of let types)
  • wppf_furnished (comma separated list of the following options – Furnished, Un-Furnished, Part-Furnished, Not Specified)
  • wppf_soldlet (hide or show – hide will hide an properties that are sold, let, let agreed, sstc – show will show all properties including sold and let)
  • wppf_orderby (can be price-asc, price-desc or latest, default is price desc unless search be location then default is nearest)
  • wppf_map (featured only, when set to yes will show results in map view.  You would normally also set the wppf_records=’-1′ to retrun all matches)
  • wppf_records (number of records to return per page)

Featured

Slider

[wppf_enquiry]

  • wppf_branch (branch number)

Enquiry

Example Usage

Show a detailed search with results pre-filtered for branch 221 hiding properties that are sold, sstc, let or let agreed.

[wppf_search wppf_branch=’221′ wppf_soldlet=’hide’]

Display the latest 4 To Buy and Commercial properties in a page

[wppf_featured wppf_search=’To Buy,Commercial’ wppf_orderby=’latest’ wppf_records=’5′]

Display the latest 5 properties in a slider

[wppf_slider wppf_orderby=’latest’ wppf_records=’5′]

Hooks and Filters

Hooks and Filters

We have included numerous hooks and filters into the plugin which experience wordpress developers will be able to use to modify the behaviour of the plugin.  We are working on publishing the full set of these but in the meantime here are a few useful examples

Setting the default results view to grid

function my_default_view( $example ) {
return ‘grid’;
}
add_filter( ‘wppf_query_wppf_view’, ‘my_default_view’ );

Set the default drop-down values for Min Rent/Max (search forms)

function my_min_rent($rentlist) {
return array(100,150,200,250,300,350,400,450,500,600,700,800);
}
add_filter(‘wppf_filter_minrent’, ‘my_min_rent’);

function my_max_rent($rentlist) {
return array(600,700,800,1000,1500,2000);
}
add_filter(‘wppf_filter_maxrent’, ‘my_max_rent’);

Set the default drop-down values for Min/Max Price (search forms)

function my_min_price($rentlist) {
return array(25000,50000,60000,70000,80000,90000,100000,110000,120000,125000);
}
add_filter(‘wppf_filter_minprice’, ‘my_min_price’);

function my_max_price($rentlist) {
return array(100000,110000,120000,125000,130000,140000,150000,160000,170000,175000,180000,190000,200000);
}
add_filter(‘wppf_filter_maxprice’, ‘my_max_price’);

Templates and Layout Customisation

TEMPLATES / CUSTOMISATION

This section is intended for developers and theme builders and explains how to customise the WP Property Feed layouts.  There are 12 layout files that sit in the templates directory of the plugin and all of these can be copied into the root directory of your theme to override the plugin defaults.  Simply make a copy of the templates you wish to override in your theme and the plugin will automatically use these instead, this is the only safe way to modify the layout templates.  You can also override the plugin stylesheet by also making a copy in your theme but you will need to dequeue and then enqueue your versions in your theme functions.php as follows;

add_action('wp_enqueue_scripts', 'mytheme_enque', 101);
function mytheme_enque() {
    wp_dequeue_style('wppf_properties');
    wp_enqueue_style('wppf_properties' locate_template('wppf.css'));
}

Archive Template

The plugin stores properties as a custom post type (wppf_property) so the archive naming follows the standard wordpress structure.  We include a standard top level archive file archive-wppf_property.php but you could also create specific taxonomy templates in addition.  The branch, property_area and property_type tags are all defined to allow for additional archive pages to be created within your theme.  This template defines the layout of the results page for the property search and you will note from version that it takes the layout property from the plugin settings to return various different layouts.  You can simply discard these and use your own layout if you wish.  The main thing to note is the inclusion of wppf_layout_results sub-template which displays the property results.

Single Template

Just as we have the standard archive template we also include the standard single one single-wppf_property.php.  This is the template that displays the property details.  In our version this is simply a container for the sub-template wppf_layout_property

wppf_layout_results.php (wppf_layout_results_nomap.php)

Template to display the property results with tabs for grid, list and map (not the nomap version excludes the map tab as this is indended for templates where the map is always present alongside the results).  The template uses standard WordPress loop methodology so provided you are familiar with wordpress coding the code within should be clear.  There is an explanation of the custom post type structure further down.

wppf_layout_map.php

Map layout which is very basic.  This includes a function to create the javascript map pins and a div map container.  Care should be taken to include both and maintain the div id naming.

wppf_layout_slider.php

Template for the full width property slider used by the wppf_slider shortcode

wppf_layout_featured.php

Template for the featured properties shortcode wppf_featured.

wppf_layout_search.php and wppf_layout_quicksearch.php

Templates for the two search shortcodes wppf_search and wppf_quicksearch respectively

wppf_layout_widgetsearch.php

Template for the Property Search widget.

wppf_layout_property.php

Template used in the single page to display the full property details.  See the full details of the Custom Post Type for details on the properties available

wppf_layout_enquiry.php

Template used for the wppf_enquiry shortcode.  This makes use of google reCaptcha and will email contents to the branch in question.  The fields on the form are specifically named to match the Vebra enquiries api so cannot be altered.

Custom Post Type – wppf_property

The plugin pulls all the feed data into a single custom post type.  This works just like any other custom post type with title, description, slug and featured image all available as normal.  In addition to this there are a number of taxonomies and meta data attached that can be used in your templates;

Taxonomies

  • branch – Name is the name of the branch but also includes meta fields phone and email.  We provide a function wppf_get_branch_address to get the branch address
  • property_area – This is will be To Buy, To Rent or Commercial
  • property_type – This links the property to the property type (House, Flat, etc)

Meta-data

  • featured – 1 or 0 – whether the property is featured or not
  • uploaded – date first uploaded
  • updated – date last updated
  • available – date property available
  • address_name
  • address_street
  • address_locality
  • address_town
  • address_postcode
  • address_custom
  • agent_ref
  • price_postfix
  • price_qualifier
  • price_currency (three letter currency code)
  • price_display (1 = yes, 0 = no)
  • price
  • fees
  • furnished (1 or 0)
  • let_type (i.e student, professional etc)
  • longitude
  • latitude
  • web_status (For Sale, SSTC, etc)
  • custom_status
  • premium
  • service_charge
  • rateable_value
  • let_bond
  • newbuild (1 or 0)
  • groundrent
  • propertyarea_sqft
  • propertyarea_sqm
  • landarea_unit
  • landarea
  • bedrooms
  • receptions
  • bathrooms
  • garden (1 or 0)
  • parking (1 or 0)
  • user1 (User specific fields – Alto only)
  • user2 (User specific fields – Alto only)
  • rm_qualifier
  • bullets
  • files (assoc array)
    • sortorder
    • filetype (0- Image, 1 – Map, 2 – Floorplan, 3 – 360, 4 – eHouse, 5 – Ipix, 7 – PDF, 8 – External URL, 9 – EPC, 10 – HIP, 11 – Virtual Tour)
    • name
    • url
  • pargraphs (assoc array)
    • sortorder
    • filesortorder – cross reference to files sortorder
    • name
    • dimensions
    • description

Theme Support

ALL THEMES

We have designed the plugin to use standard wordpress styles and as such it should work seamlessly with most wordpress themes, so colours and font styles should cascade down through our plugin.   Occasionally themes will use their own bespoke styling system in which case we allow you to override our plugins styles with your own.

In general the plugin is intended to work with general themes that do not already have property features already included as our plugin will provide all the property display and search functionality you require.  However, we are now starting to build connectors that will join our plugin to popular property themes so that your back-office properties will automatically appear in the property theme.

SUPPORTED PROPERTY THEMES

In order to provide the connection between our plugin and a property feed you need to download and install a plugin addon (in the form of another plugin).  You must have the WP Property Feed plugin installed and enabled and also the property theme installed and enabled in order for the connector to work.  Once the connector is installed and activated you can just use all the features of the property theme as normal.  All our connectors are provided free via the wordpress.org plugin repository.

Radius Filter

To change the default radius ranges in the search filter we have provided a wordpress filter.  You can add the following code snippet to your themes functions.php file to make use of this filter to change the radius  values;

function my_radius_filter( $data ) {
    return array(0.5,1,2,3,5,10);
}
add_filter('wppf_filter_radius', 'my_radius_filter');