The shortcode [matador_jobs]
displays a list of jobs and paginates the list if needed. It is the most common shortcode our users deploy on their sites and is used to display jobs on sites that do not use a WordPress archive template for job display.
This shortcode also has three alias shortcodes which pre-set one of the parameters and makes your code more readable. They are [matador_jobs_list]
, [matador_jobs_listing]
, and [matador_jobs_table]
.
Parameters
as
: Select the type/format of the job list. Accepts ‘listing’ for blocks of jobs stacked on top of each other, ‘list’ for an unordered list of links to jobs using the job title as the link text, ‘select’ for a drop down form field of job titles, and ‘table’ for an HTML table of job properties. Default is ‘listing’.
fields
: List of fields to show, separated by commas. Accepts ‘title’, ‘content’, ‘excerpt’, ‘link’ (for a link to the job), all valid job taxonomies (including ‘category’ and ‘location’) and all custom fields. When ‘as’ is ‘list’ or ‘select’, this is ignored. When ‘as’ is ‘table’, the table column headers are the name of field capitalized, but can be renamed by passing a pipe | character and then a label, ie: category|Industry
would result in a table with a column heading of “Industry” that displays the value of the category taxonomy.
content_limit
: Limit the length of the ‘content’ field output. Accepts ‘full’ for the whole job description, ‘excerpt’ for only the site default excerpt limit, or a whole number representing the number of words to show before truncation. Ignored when ‘as’ is ‘list’ or ‘select’. Default is 240.
jobs_to_show
: How many jobs to show per page. If there are more total jobs than shown, pagination links will be added. Accepts any positive integer or -1 to show all jobs (use with caution). Defaults to 100 when ‘as’ is ‘list’ or ‘select’, 25 when ‘as’ is ‘table’, and 12 when ‘as’ is not set or ‘listing’.
backfill
: Minimum number of jobs to show. When this shortcode is used to present related jobs, for example, if no jobs are related, the space can be “backfilled” with extra jobs so the section isn’t empty. Setting this argument will ensure some jobs are shown even when no jobs fit the query. It accepts any positive integer or null/not set to disable backfill. Default is null/not set. If backfill
is greater than jobs_per_page
, backfill
will be changed to jobs_per_page
.
paginate
: Whether to show pagination when the query can produce more results than jobs_per_page
. Default is true. Pass false or 0 to disable pagination. If including jobs in a sidebar or related posts section, you should disable pagination.
search
: Limits jobs to the specified search term, which will search title and content (job description). Default is null/not set.
$taxonomy
: Any registered job taxonomy, of which ‘category’ and ‘location’ are default, each can be passed an argument. Accepted values are a string of taxonomy term IDs or URL slugs. For example, to show jobs only from the Categories ‘Administrative’ or ‘Human Resources’, you’d add category=administrative,human-resources
.
selected
: Determines which options are selected when ‘as’ is ‘select’. Accepts an integer WordPress ID or list of comma-separated WordPress Job IDs. Do not pass Bullhorn Job IDs. Default is the value of the URL Query String or not set/null.
multi
: When ‘as’ is ‘select’, determines whether the drop-down allows multiple selections. Pass 1 or true to enable. Defaults to false.
id
: Set an HTML id value for the job wrapper. Defaults to not set/null.
class
: Provide a string to add a class name to the wrapper. Also helpful for designers to style these jobs. Default is not set/null.
Examples
The default shortcode displays the 12 most recent jobs, with the fields title, meta, content, and link, with pagination to see more, in a ‘listing’ layout:
[matador_jobs]
Show the 3 most recent jobs from the “Administrative” category, but backfill if there are no jobs in the category, with the fields title, meta, content, and link, without pagination, in a ‘listing’ layout:
[matador_jobs category=administrative pagination=false jobs_per_page=3 backfill=3]
Show a bullet list of the 5 newest jobs in the location of “Arizona” without pagination:
[matador_jobs as=list location=arizona jobs_per_page=5 pagination=false]
Show a table of jobs with the title labeled “Job Title”, location labelled “Location”, and link labelled “See More”, and show 25 results.
[matador_jobs as=table fields="title|Job Title, location, link|See More"]