Format Job Single and Archive Templates with Page Builders

In this help doc, we’ll help you add shortcodes before and after your job description as imported from Bullhorn. This is important if your site relies on shortcode-based “page builders” like Divi and others.

Before we begin, let us take a moment to stand on our soapboxes: since the release of WordPress 5.0, a powerful “page builder” is now a core feature. It’s called Gutenberg. Unlike most “page builders” which force formatting and code into WordPress database tables via Shortcodes, Gutenberg outputs pure HTML5 code with some embedded CSS. With the future of WordPress and the internet in general being about managing content for publishing in external apps and “headless” websites which do not have access the code that converts Shortcodes into readable content, we encourage you, especially if you are building new websites/themes to skip shortcode-based builders and use Gutenberg and Gutenberg plugins moving forward.

That said, if your existing site relies on Divi or other popular shortcode based themes or page builders, you have some options. We need to pause and make sure we get the terms right.

An “archive” is a WordPress term for the layout and design of a list of posts. In our case, a “post” is a “job” and the “job archive” is the listing of all jobs. This is typically searchable or filterable.

A “single” is a WordPress term for the layout and design of a single post. In our case, this is the page that shows the job description and optionally the application form (or link to one).

Job “Archives” and Page Builders

For themes with a page builder, its very easy to override your Job Archive and use a page built with your page builder instead. Simply:

  1. Create a new Page with your page builder.
  2. Add the [matador_jobs] shortcode where you want your job list to show up.
  3. Optionally add other Matador shortcodes to extend search or filtering capabilities.
  4. Save your page.
  5. Go to Matador Jobs > Settings and scroll to the bottom looking for the setting Job Board Location. Change “Use Archive” to the page you just created.

Job “Single” pages and Page Builders

Its a lot more complicated to use Page Builders with job single pages. Typically, a “single” page is mostly filled with content from the post’s content (in our case, job’s description).

Your job descriptions come from Bullhorn. Like all job data, Matador downloads the job description from Bullhorn and presents it as formatted. Bullhorn uses a simple visual editor that saves basic HTML into your job description including HTML that formats paragraphs, lists, blockquotes, bold and italic fonts, and more.

If your site requires additional formatting, you unfortunately can’t just edit the job’s description in your WordPress site, because on the next sync, it will be overwritten again by Matador to what it finds on Bullhorn. Therefore, we need to get creative. You have really three options:

  1. Turn off the page builder for Matador Job single pages and create a single-matador-job-listings.php template.
  2. Use the_content()filter to insert the formatting shortcodes before and after the job description.
  3. Create a third “Job Description” field using the field editor in Bullhorn where you can place a job description with WordPress shortcodes, and then tell Matador to import that field in leu of the standard description field.

Option 1: Turn off the page builder for Matador Job single pages and create a single template.

If you want specifically formatted look to your jobs, it is most ideal to skip the page builder and develop a true template for your job. This is well documented elsewhere on the internet, but here is a quick summary:

  • Look up the documentation of your page builder and find how to disable it for the “single” of a given post type. Some page builders may not be on by default for a “custom post type” like Matador’s Job Listing, so you may skip this step.
  • Create a copy of the single.php file inside your theme’s or your child theme’s folder. Name it single-matador-job-listings.php.
  • Use HTML 5 to create the desired layout and modify your theme’s or your theme child’s stylesheet with desired formatting.

Option 2: Use the_content()filter to insert the formatting shortcodes before and after the job description.

If you really like using your page builder’s shortcode-based tools, take a short moment to create a “mock” job using your page builder. Then, view the “text” or “source” created by your page builder and copy it into a text editor.

Evaluate the “source” and determine what goes before and what goes after a standard job description. Everywhere you want dynamic content, ie: a job field like the location or the job ID, replace the example content with the [matador_job_field] shortcode for the field.

For example, to get the Job ID, use [matador_job_field name="bullhorn_job_id"].

Then, copy this code snippet info your theme’s functions.php file. Put your before and after shortcodes in place of the placeholders.

It is important to note that, by default, most page builders will be off for custom post types, including Matador’s Job post type. Page builders load special templates for post types upon which they are enabled, so you may need to figure out how to “turn on” the page builder for your jobs.

Option 3: Create a new field in Bullhorn for “WordPress Description” and included formatted descriptions with shortcodes at Bullhorn-level.

As we work hard to document as much of Matador as possible, we admit we have a lot of work to do. There is a filter that, as of this writing, is undocumented on our website but has code-level documentation that enables you change which field is used to import the description. The filter is named matador_import_job_description_fieldand its documentation can be found in /includes/bullhorn/bullhorn-import.php. By passing a custom field mapped to your Bullhorn job, ie: “WordPress description” as customTextBlock1, you could write job descriptions with embedded shortcodes in Bullhorn that will be imported to WordPress during sync. Note the following:

  • Matador offers many paths to customize your site but cannot support every way they’re used. Our support is limited to generally out of the box settings, and should you need further help implementing this, we may send you a quote for advanced support fees.
  • Recruiters are not coders, and the Bullhorn custom text block editor will not visually show what the job will look like in WordPress, which would have access to the visual page builder editor.
  • A job published without content in the Custom Text Block aka “WordPress Description” may result in a job that is not imported properly during sync.