The listings Field API contains all API methods for creating and retrieving field metadata.


Methods: fields__


assign_class($data) - Used to add an existing listing field in OR to a property class:

assign_class(array $data) : \multitype:string


Returns: (multitype:string)

['error'] - TRUE/FALSE - Error status of the assign  request

['error_msg'] - TEXT - Error message returned (if ['error'] = TRUE).

['field_id'] - INT -  Numeric listing field ID# of the field (listingsformelements_id).

['class_id'] - INT - Numeric class ID  ID# the field was assigned to.


Parameters:

$data (array)

Expects an array containing the following array keys:

$data['class'] - INT - Class ID that we are assigning this field to

$data['field_id'] - INT - Field ID to assign




create($data) - Used to insert a listing field into a class.

create(array $data) : array


Returns: (array)

['error'] - TRUE/FALSE - Error status of the create request

['error_msg'] - TEXT - Error message returned (if ['error'] = TRUE).

['field_id'] - INT - Numeric listing field ID# of the new field (listingsformelements_id).


Parameters:

$data (array)

Expects an array containing the following array keys:

$data['resource'] - TEXT - What type of resource are you creating a field for. Allowed Options are "listing".

$data['class'] - ARRAY - Array of property class ID that you want to insert an listing field into.

$data['field_type'] - TEXT - Type of field to create. Valid options are 'text','textarea','select','select-multiple','option','checkbox','divider','price','url','email','number','decimal','date','lat','long'

$data['field_name'] - TEXT - Name of field to create

$data['field_caption'] - TEXT - Caption to display for field.

$data['field_elements'] - ARRAY - Array of options if this is a select type of field.

$data['rank'] - INT  - Order of Field.

$data['search_rank'] - INT - Order of Field on Search pages.

$data['search_result_rank'] - INT - Order of field on search results page.

$data['required'] - BOOLEAN - Field is required: TRUE/FALSE

$data['location'] - TEXT - Template Location to display field at.

$data['display_on_browse'] - BOOLEAN - Should this field be displayed on the search results page?.

$data['search_step'] - INT - Value to step search values by for min/max fields

$data['display_priv'] - INT - 0 = Show Field to All Visitors, 1 = members & Agents, 2 = Agents Only, 3 = Admin Only

$data['field_length'] - INT - Maximum Length of Field

$data['tool_tip'] - TEXT -Tooltip to show

$data['search_label'] - TEXT - Label to show user when searching this field

$data['search_type'] - TEXT - Search field type, Allowed Values: 'ptext','optionlist','optionlist_or','fcheckbox','fcheckbox_or','fpulldown','select','select_or','pulldown','checkbox','checkbox_or','option','minmax','daterange','singledate','null_checkbox','notnull_checkbox'

$data[$searchable'] - BOOLEAN - Is the field searchable?




(revised in v3.2.10)

metadata($data) - Used to get internal listing or Agent or Member field metadata (information).

metadata(array $data) : array


Returns: (array)

['error'] - TRUE/FALSE - Error status of the lookup request

['error_msg'] - TEXT - Error message returned (if ['error'] = TRUE).

['fields'] - ARRAY - Array of all field info. Key is the numeric 'listingsformelements_id',  'agentformelements_id', 'memberformelements_id' or 'feedbackformelements_id' whichever resource is applicable.

['fields']['field_id'] - INT - Numeric listing field ID#  

['fields']['field_type'] - TEXT - Valid options are 'text','textarea','select','select-multiple','option','checkbox','divider','price','url','email','number','decimal','date','lat','long'

['fields']['field_name'] - TEXT - OR's internal field name for this field.

['fields']['field_caption'] - TEXT - Description of the field. e.g. 'List Price' or 'Bedrooms'

['fields']['default_text'] - TEXT - Default text or values that will display pre-selected in the search form

['fields']['field_elements'] - ARRAY - Array of any defined field elements

['fields']['rank'] -  INT  - Numeric order/rank of Field.

*['fields']['search_result_rank'] - INT -  Numeric search results page order/rank of Field

*['fields']['required'] - YES/NO - Is this field required when creating a listing

['fields']['location'] - TEXT - Display location in OR's Listing Editor or Lead Form Editor

*['fields']['display_on_browse'] - YES/NO - Does this field display on the search_results page.

*['fields']['searchable'] - BOOLEAN - Is field set to be used for searches

*['fields']['search_type'] - TEXT - Search Type of field, if field set to be searchable.

*['fields']['search_label'] - TEXT - Text label used if field is used for searches.

*['fields']['search_step'] - INT - Numeric step value if field is used for searches and is a min/max search type.

+['fields']['display_priv'] - TEXT - Set only if the field is restricted from viewing to only certain user types

['fields']['tool_tip'] - TEXT - Any defined tooltip text

(* only applicable to 'listing' resource.  + not applicable to 'member' and 'feedback' resouorces)


Parameters:

$data (array)

Expects an array containing the following array keys:

$data['resource'] - TEXT - What resource do you want to get fields for. Allowed Options are 'listing', 'agent', 'member' or 'feedback'.

$data['class'] - ARRAY - Optional array of property class IDs when reading the listing resource. Only fields assigned to these IDs will be returned.

$data['field_id'] - INT  - Optional Field ID. If set only the metadata for the field specified is returned..

$data['searchable_only'] - BOOLEAN - Optional - If set to 'true' only fields set to be searchable are returned.


'listing' resource example:

<?php

       //Call the API and Get all Field  information for Property Class 1

       $pclass_list = array(1);

       $result = $api->load_local_api('fields__metadata',array(

               'resource'=>'listing',

               'class'=>$pclass_list

       ));

       if($result['error']){

               //If an error occurs die and show the error msg;

               die($result['error_msg']);

       }

       //No error so assign the array of fields that were returned to $field_list.

       $field_list = $result['fields'];

       

       // format and output the contents of the $field_list array so the keys

       // and values can be viewed.

       echo '<pre>';

       print_r($field_list);

       echo '</pre>';

?>


'agent' resource example that targets a specific field_id:

<?php

       //get all metadata for Agent field that is agentformelements_id = 5

       $result = $api->load_local_api('fields__metadata',array(

               'resource'=>'agent',

               'field_id' => 5

       ));


       if($result['error']){

       //If an error occurs die and show the error msg;

               die($result['error_msg']);

       }

       //No error so assign the array of fields that were returned to $field_list.

       $field_list = $result['fields'];

       

       // format and output the contents of the $field_list array so the keys

       // and values can be viewed.

       echo '<pre>';

       print_r($field_list);

       echo '</pre>';


?>



values($data) - Used to obtain a list of unique values and the number of listings that match each unique value for a given listing field.

values(array $data) : array


Returns: (array)

['error'] - TRUE/FALSE - Error status of the lookup request

['error_msg'] - TEXT - Error message returned (if ['error'] = TRUE).

['field_values'] - ARRAY - Array of all unique values that exist for this listing field.

['field_counts'] - ARRAY - Array containing the number of listings that match each unique stored value for this listing field. The keys of this array equal the unique field_values


Parameters:

$data (array)

Expects an array containing the following required array keys:

$data['pclass'] - ARRAY - Array of property class ID of the field you want to obtain values for.

$data['field_type'] - TEXT - Type of field. Valid options are 'decimal', 'number', or ''

$data['field_name'] - TEXT  - Name of field to lookup


example:

<?php

       //lookup listing counts that match each number of bedrooms

       //only calculate for residential class (class ID#1)

       $pclass = array(1);

       $result = $api->load_local_api('fields__values',array(

               'pclass'=> $pclass,

               'field_name'=>'beds',

               'field_type'=>'decimal'

       ));

       

       // format and output the contents of the $result array so the keys

       // and values can be viewed.

       echo '<pre>';

       print_r($result);

       echo '</pre>';

?>