6. Retrieving data

1. Introduction

Since our plugin is built on top of Advanced Custom Fields Pro, you can use their functions to retrieve a property's individual fields. This is especially useful when building the single property page.

get_field: https://www.advancedcustomfields.com/resources/get_field/
get_fields: https://www.advancedcustomfields.com/resources/get_fields/
the_field: https://www.advancedcustomfields.com/resources/the_field/

Examples:

get_field('location')['street']
// Returns string

get_field('features')['images']
// Returns array of images

get_field('price')['amount']
// Returns integer

This allows for very easy data manipulation.

A complete overview of all of the included fields will be added to this documentation at a later stage.

Show available fields of a single property

Run get_fields() on a single-estate.php page to see all of the fields of a property.

Show all available properties

Perform a var_dump() of the ::list() method to see all published properties, and its available fields.

1.1. Template structure

This plugin offers you a lot of freedom on how to implement SweepBright within your website. We only require a naming convention for the template of a single property page (single-estate.php).

Property overview page

e.g. page-estates.php

The above filename is just an example. You're free to name this template however you want.

Single property page

e.g. single-estate.php

This template file is required. This is the template where the single property page will be rendered. Methods as seen in chapter 3 only work within this template.

2. Listing properties

2.1. List properties

Returns an array containing all of the published properties (paginated). This method is also used for filtering and sorting. The returned data is a multi-dimensional PHP array, which can be easily transformed into a JSON object, if you want to use JavaScript.

WP_SweepBright_Query::list([
  'page' => <integer>, // Current page
  'recent' => <enum>, // false, <number of properties>
  'mapMode' => <boolean>, // when set to true it disables pagination and only shows relevant information to display on map markers
  'showAll' => <boolean>, // when set to true it disables pagination and lists all properties (not recommended)
  'sort' => [
    'order' => 'desc', // "desc", "asc"
    'orderBy' => <enum>, // "relevance", "price", "date"
  ],
  'filters' => [
    'status' => <string> or <array>, // false, "available", "sold", "option", "under_contract", "rented"
    'new_home' => <boolean>, // Only show properties with their general condition set to 'new'
    'negotiation' => <enum>, // false, "sale", "let", "projects", "sale_non_projects"
    'agent' => <array>, // false, e.g. [tromp.jess@hudson.biz, mary.ann@hudson.biz]
    'category' =>  <array>, // See all of the categories in the docs under "type": https://website.sweepbright.com/docs/#sweepbright-website-api-endpoints-estate
    'subcategory' => <array>, // See all of the subcategories in the docs under "sub_type": https://website.sweepbright.com/docs/#sweepbright-website-api-endpoints-estate
    'facilities' => [
      'bedrooms' => [
        'min' => <integer>,
        'max' => <integer>,
      ],
    ],
    'price' => [
      'min' => <decimal>,
      'max' => <decimal>,
    ],
    'plot_area' => [
      'min' => <decimal>,
      'max' => <decimal>,
    ],
    'liveable_area' => [
      'min' => <decimal>,
      'max' => <decimal>,
    ],
    'location' => [
      'lat' => <decimal>, // Latitude coordinate
      'lng' => <decimal>, // Longitude coordinate
    ],
  ]
]);

Example request:

WP_SweepBright_Query::list([
  'page' => 1,
  'recent' => false,
  'mapMode' => false,
  'showAll' => false,
  'sort' => [
    'order' => 'desc',
    'orderBy' => 'relevance',
  ],
  'filters' => [
    'status' => false,
    'new_home' => false,
    'negotiation' => false,
    'agent' => false,
    'category' => ['apartment'],
    'subcategory' => ['loft', 'duplex', 'penthouse'],
    'facilities' => [
      'bedrooms' => [
        'min' => false,
        'max' => false,
      ],
    ],
    'price' => [
      'min' => false,
      'max' => false,
    ],
    'plot_area' => [
      'min' => false,
      'max' => false,
    ],
    'liveable_area' => [
      'min' => false,
      'max' => false,
    ],
    'location' => [
      'lat' => false,
      'lng' => false,
    ],
  ]
]);

Example response:

[
  'totalPages' => 5
  'totalPosts' => 50,
  'estates' => [
    [
      'id' => '101', // WordPress Post ID
      'permalink' => 'https://estate-website.com/estates/1001/new-apartment-for-sale'
      'date' => 1614769176 // Unix timestamp
      'meta' => [
        'estate' => [
          'id' => '000-000-000-000', // SweepBright ID,
          'status' => 'option', // available, option, rented, sold, prospect, bid, under_contract
          ...
        ],
        'location' => [
          'street' => 'Grove Street',
          'number' => 1,
          ...
        ]
        ...
      ]
    ],
    ...
  ]
]

Tip:

In order to get a complete overview of all of the data being returned by the list() method, it's best to inspect it with var_dump(). The plugin has all of SweepBright's property information available. You can see all available data here.

2.2. List units

SweepBright has a concept called "projects & units". What this means is that you can have properties with multiple units, such as an apartment building with multiple units, or a new-build project with multiple lots. Within SweepBright, the project itself is basically the same as a regular property. The biggest difference is that projects have multiple units. Units are also similar to regular properties, with the exception that they have a relationship to their parent project by having project_id linked to their parent.

The example below explains how to retrieve a list of units from a project with ID: 000-000-000.

WP_SweepBright_Query::list_units([
  'is_paged' => <boolean>, // Enables or disabled pagination
  'page' => <integer>, // The current page (pagination is applied automatically)
  'ignore_self' => <boolean>, // Show or hide the current unit (useful if you're showing a list of related on a single unit page)
  'project_id' => <string> // The project's ID
]);