Matador Docs Tutorial: Importing & Using Custom Location Data

tutorial_matador_custom_location_data_step_2.php

<?php // Omit opening PHP tag

add_filter( 'matador_bullhorn_import_fields', 'mdocs_tutorial_custom_location_data_step_2' );
/**
 * Matador Docs Tutorial: Custom Location Data Step 2 - Importing the Field
 *
 * Example below imports Bullhorn field named 'customText1', calls it 'location_area', declares it a 'string', and declares
 * as a custom field type.
 *
 * @since 2020-03-30
 *
 * @copyright 2020, Matador Software, LLC
 * @author Jeremy Scott, Matador Software LLC
 * @link https://matadorjobs.com/support/documentation/understanding-and-customizing-the-job-location/
 *
 * @param $fields
 *
 * @return array
 */
function mdocs_tutorial_custom_location_data_step_2( $fields ) {
	$field_to_add = [
		'customText1' => [ // Name of field per Bullhorn Field Mappings (not its label)
			'name'   => 'location_area', // Set name for meta when 'saveas' is 'meta'.
			'type'   => 'string', // Specify type for sanitization, default 'string'
			'saveas' => 'custom', // Options are 'core', 'meta', 'custom'. Default 'custom'
		],
	];
	return array_merge( $fields, $field_to_add );
}

tutorial_matador_custom_location_data_step_3.php

<?php // omit opening PHP tag
add_action( 'matador_import_before_save_job_location', 'mdocs_tutorial_custom_location_data_step_3', 10, 2 );
/**
 * Matador Docs Tutorial: Custom Location Data Step 3 - Saving The Data Point
 *
 * In this example, we'll save a post meta for a custom location data point (customText1).
 *
 * @since 2020-03-30
 *
 * @copyright 2020, Matador Software, LLC
 * @author Jeremy Scott, Matador Software LLC
 * @link https://matadorjobs.com/support/documentation/understanding-and-customizing-the-job-location/
 *
 * @param stdClass $job The Job Object (from Bullhorn)
 * @param int $wpid The WordPress Job Post Type ID
 *
 * @return void
 */
function mdocs_tutorial_custom_location_data_step_3( $job, $wpid ) {
 if ( isset( $job->customText1 ) ) { 
  // Use update_post_meta as opposed to save_post_meta. Update still creates new when it previously didn't exist.
  update_post_meta( $wpid, 'location_area', $job->customText1 );
 }
}

tutorial_matador_custom_location_data_step_4a.php

<?php // omit opening PHP tag
add_filter( 'matador_import_job_general_location', 'mdocs_tutorial_custom_location_data_step_4a', 10, 3 );
/**
 * Matador Docs Tutorial: Custom Location Data Step 4a - Using Custom Location Data Point in Job General Location
 *
 * In this example, we'll use the custom post meta for a custom location data point for job general location.
 *
 * @since 2020-03-30
 *
 * @copyright 2020, Matador Software, LLC
 * @author Jeremy Scott, Matador Software LLC
 * @link https://matadorjobs.com/support/documentation/understanding-and-customizing-the-job-location/
 *
 * @param string $general_location
 * @param array  $location_data. Values are "street", "city" for city or locality, "state", "zip" for ZIP or Postal Code, and "country"
 * @param int    $wpid ID of the current job post.
 *
 * @return string $general_location
 */
function mdocs_tutorial_custom_location_data_step_4a( $general_location, $location_data, $wpid ) {
  $location_area = get_post_meta( $wpid, 'location_area', true );
  
  if ( $location_area ) {
    $general_location = esc_html( $location_area );
  }
  
  return $general_location;
} 

tutorial_matador_custom_location_data_step_4b.php

<?php // omit opening PHP tag
add_filter( 'matador_import_location_taxonomy_allowed_fields', 'mdocs_tutorial_custom_location_data_step_4b_1' );
/**
 * Matador Docs Tutorial: Custom Location Data Step 4b-1 - Allowing Custom Location Data Point for Location Taxonomy
 *
 * To protect you, only allowed fields can be used to set the location taxonomy term, so we must allow it first.
 *
 * @since 2020-03-30
 *
 * @copyright 2020, Matador Software, LLC
 * @author Jeremy Scott, Matador Software LLC
 * @link https://matadorjobs.com/support/documentation/understanding-and-customizing-the-job-location/
 *
 * @param array $allowed_fields
 *
 * @return array
 */
function mdocs_tutorial_custom_location_data_step_4b_1( $allowed_fields ) {

  $allowed_fields[] = 'location_area';

  return $allowed_fields;
}

add_filter( 'matador_import_location_taxonomy_field', 'mdocs_tutorial_custom_location_data_step_4b_2', 10 );
/**
 * Matador Docs Tutorial: Custom Location Data Step 4b-2 - Using Custom Location Data Point for Location Taxonomy
 *
 * @since 2020-03-30
 *
 * @copyright 2020, Matador Software, LLC
 * @author Jeremy Scott, Matador Software LLC
 * @link https://matadorjobs.com/support/documentation/understanding-and-customizing-the-job-location/
 *
 * @param string $field_to_use
 *
 * @return string $field_to_use
 */
function mdocs_tutorial_custom_location_data_step_4b_2( $field_to_use ) {

  $field_to_use = 'location_area';

  return $field_to_use;
}