Matador Jobs 3.9.0 introduced the matador_jobs_orderby template function, matador_jobs_orderby shortcode, and the ability to switch on orderby arrows on the jobs table layouts by passing setting the column_orderby argument to true.
There are a number of sensible defaults which can be used to determine the order of jobs across these new features, however you may have a custom field which you wish your users to be able to order jobs by too. Here is how you can add your custom field to the available orderby options.
Where do the orderby defaults come from?
The default options come from Job_Listing::job_orderby_options()
/**
* Job Orderby Options
*
* Returns an array of orderby options for the job listings.
*
* @since 3.9.5
*
* @return array
*/
public static function job_orderby_options(): array {
$options = [
'publication_date_newest' => [
'label' => __( 'Date Published (newest first)', 'matador-jobs' ),
'orderby' => 'date',
'order' => 'DESC',
],
'closing_date_newest' => [
'label' => __( 'Closing Date (newest first)', 'matador-jobs' ),
'orderby' => 'meta_value_num',
'meta_key' => 'dateEnd',
'order' => 'DESC',
],
'title' => [
'label' => __( 'Job Title (a-z)', 'matador-jobs' ),
'orderby' => 'title',
'order' => 'ASC',
],
'source_id' => [
'label' => __( 'Source ID (ascending)', 'matador-jobs' ),
'orderby' => 'meta_value_num',
'meta_key' => '_matador_source_id',
'order' => 'ASC',
],
'random' => [
'label' => __( 'Random', 'matador-jobs' ),
'orderby' => 'rand',
'order' => 'ASC',
],
];
/**
* @wordpress-filter `matador_template_job_info_show_pay`
* Show the Pay in the Template (formerly just Job Info Bar)
*
* Override the settings option on whether to show/hide the Salary in the Template
*
* @since 3.8.4
*
* @return boolean
*/
if ( apply_filters( 'matador_template_job_info_show_pay', Matador::setting( 'jsonld_salary' ) ) ) {
$salary_orderby_field = Matador::setting( 'salary_orderby_field' );
$options['salary'] = [
'label' => __( 'Salary (highest first)', 'matador-jobs' ),
'orderby' => 'meta_value_num',
// @todo - Nesting settings call like this feels wrong - see if there's a better way to do this.
'meta_key' => Matador::setting( $salary_orderby_field ),
'order' => 'DESC',
];
}
/**
* @wordpress-filter `matador_job_search_orderby_options`
* Modify the Options for the Job Search Orderby
*
* @since 3.9.5
*
* @param array $options
* @return array
*/
return apply_filters( 'matador_job_search_orderby_options', $options );
}
To enable users to order jobs by your custom field, you’ll need there to be an element in the array returned by this function for your custom field. You can achieve this by using the ‘matador_job_search_orderby’ filter.
Adding a custom field to the orderby options
Here’s an example where the ‘yearsRequired’ field is added to the options so users can sort jobs by the number of years of experience they require.
add_filter( 'matador_job_search_orderby_options', 'matador_example_add_custom_fields_to_orderby_options', 10 );
function matador_example_add_custom_fields_to_orderby_options( $options ) {
$options[ 'yearsRequired' ] = [
'label' => __( 'Experience Required (yrs)', 'your-textdomain' ),
'orderby' => 'meta_value_num',
'meta_key' => 'yearsRequired',
'order' => 'ASC',
];
return $options;
}
You’ll notice the array element we’re adding has a specific set of keys, here’s some more information on what each of these keys is for:
- label: This is the label that will be used to display this option in the orderby select.
- orderby: This value will be passed to the ‘orderby’ key of WP_Query, when we’re ordering by post metadata it needs to be ‘meta_value_num’ for numerical sorting, or ‘meta_value’ for alphabetical sorting. See here for more details on this
- meta_key: This is the key of the postmeta we want to orderby. Exactly what this is will depend on which field you’re importing, and the key this fields data is saved to in postmeta
- order: This is the default order which will be passed to WP_Query if not overriden using the matador-jobs-order query parameter.