Template Override Guide

LimeStaff ships with a set of front-end templates that control how job listings, single job pages, search filters, pagination, and the application form are rendered. Every one of these templates can be overridden from your theme — no plugin file edits required.

How Template Overrides Work

LimeStaff uses a WooCommerce-style template loader. When a template is requested, the plugin checks for a theme override first:

  1. Theme — wp-content/themes/your-theme/limestaff/{template}.php
  2. Plugin fallback — wp-content/plugins/limestaff/templates/{template}.php

The lookup is handled by the limestaff_locate_template() helper, which calls WordPress core’s locate_template() under the hood.

Getting Started

  1. Create a limestaff folder in your active theme or child theme’s root directory.
  2. Copy the template you want to customize from the plugin’s templates/ folder into your-theme/limestaff/.
  3. Edit the copy in your theme. Your version will take priority over the plugin’s default.
your-theme/
└── limestaff/
    ├── job.php
    ├── job-search.php
    ├── job-search-filters.php
    ├── job-search-pagination.php
    └── apply-form.php

Tip: Only override the templates you need to change. Keeping the rest on the plugin defaults means you automatically receive improvements and fixes on plugin updates.

Overridable Templates

Template File Description
job.php Single job detail page
job-search.php Job search listings page
job-search-filters.php Search and filter form
job-search-pagination.php Pagination controls
apply-form.php Job application form

Template Reference

1. job.php — Single Job

Renders the single job detail page inside a shortcode, widget, or archive context.

Loaded by: LoxoJobView::render()

Available Variables

Variable Type Description
$limestaff_job LimeStaff\Jobs\AbstractJob The LimeStaff job object (WordPress post wrapper).
$job object Raw Loxo job data object (from API / post meta).
$render_settings array Widget/shortcode render settings.
$apply_success bool Whether the visitor just submitted a successful application.
$this LoxoJobView The current LoxoJobView instance.

$limestaff_job Methods

Method Returns Description
get_rendered_title() string HTML-safe job title.
get_cleaned_job_description() string Sanitised full job description (inline styles stripped).
get_permalink() string Canonical permalink to this job.
get_source_job_id() string Original Loxo job ID.

$job Properties (Raw Loxo Data)

Property Description
$job->id Loxo job ID.
$job->company->name Company name.
$job->macro_address Location string (may be empty).
$job->salary Salary value (may be empty).
$job->job_type->name Job type label (e.g. “Full Time”).
$job->published_at ISO date string of publish date.
$job->status->id Loxo status ID.

$job Methods

Method Returns Description
get_salary_currency_symbol() string Currency symbol for salary display.

Render Settings — View Toggles

These booleans are set by the widget/shortcode and control which meta fields are visible:

Key Controls
$render_settings['view_toggles']['company'] Company name
$render_settings['view_toggles']['location'] Location
$render_settings['view_toggles']['salary'] Salary
$render_settings['view_toggles']['job_type'] Job type
$render_settings['view_toggles']['published_at'] Published date

Instance Access

$this refers to the LoxoJobView instance, giving you access to:

Method Returns Description
$this->render_apply_form_template() string Returns the rendered apply form HTML (loads apply-form.php).

2. job-search.php — Job Search Listings

Renders the main job listings page including the job cards, and loads the filter and pagination sub-templates.

Loaded by: JobSearch::render()

Available Variables

Variable Type Description
$jobs array Array of AbstractJob instances. Empty if no results.
$render_settings array Widget/shortcode render settings.
$total_pages int Total number of pagination pages.
$current_page int Current page number (1-based).
$has_more_pages bool Whether there are more pages after the current one.
$is_archive_page bool Whether this is the virtual jobs archive page.
$base_url string Base URL for pagination and form actions.
$selected_job_category_id mixed Currently selected job category ID.
$job_custom_field_list array Custom field data shown in filters (from global settings).
$has_custom_fields_filter bool Whether any custom field filter has options to display.

Each $job Object Methods

Method Returns Description
$job->id int WordPress post ID.
$job->get_link() string Permalink to the single job page.
$job->get_rendered_title() string HTML-safe job title.
$job->get_excerpt() `string\ null` Short description excerpt.
$job->get_raw_data() object Raw Loxo data object (->macro_address, ->salary, ->job_type, etc.).
$job->get_salary_currency_symbol() string Currency symbol for salary display.

Render Settings — View Toggles

Key Controls
$render_settings['view_toggles']['location'] Job location
$render_settings['view_toggles']['salary'] Salary
$render_settings['view_toggles']['job_type'] Job type label
$render_settings['view_toggles']['job_excerpt'] Job description excerpt
$render_settings['view_toggles']['apply_button'] “Apply Now” button

Sub-templates

This template loads two sub-templates that are also overridable:

<?php include limestaff_locate_template( 'job-search-filters' ); ?>
<?php include limestaff_locate_template( 'job-search-pagination' ); ?>

3. job-search-filters.php — Search & Filter Form

Renders the keyword search, category dropdown, job type dropdown, location filters, and custom field filters.

Loaded by: Included from job-search.php

Available Variables

Variable Type Description
$search string Current keyword search value.
$render_settings array Widget/shortcode render settings.
$job_category_options array Array of Option objects for job categories.
$selected_job_category_id mixed Currently selected category ID.
$job_type_options array Array of Option objects for job types.
$current_job_type mixed Currently selected job type value.
$country_options array Array of Option objects for countries.
$current_country string Currently selected country code.
$state_options array Array of Option objects for states.
$current_state string Currently selected state code.
$city string Current city filter value.
$job_custom_field_list array Custom field data with options (from global settings).
$has_custom_fields_filter bool Whether any custom field filter has displayable options.
$current_custom_fields array Currently selected custom field values from $_POST.

Option Object Methods

The category, job type, country, and state arrays contain Option objects:

Method Returns Description
->get_value() string The option value (used in form submission).
->get_name() string The display label.

Helper Functions Used

Function Description
limestaff_get_job_search_form_action_url() Returns the form action URL (respects permalink settings).
limestaff_should_render_category_dropdown( $render_settings ) Whether to show the category dropdown.
limestaff_should_render_job_type( $render_settings ) Whether to show the job type dropdown.
limestaff_filter_value_is_unset( $value ) Check if a filter value is “unset” (-1 or '').
limestaff_has_custom_field_filter( $list ) Whether custom field filters should display.

Render Settings — View Toggles

Key Controls
$render_settings['view_toggles']['filter_by_location'] Show country / state / city filters.
$render_settings['view_toggles']['view_category'] Show category dropdown (when no tag filter is set).
$render_settings['view_toggles']['view_role'] Show job type dropdown.

Inline JavaScript

The default template includes inline <script> that handles:

  • Pagination (go_to_page action) — Appends jobs_page query param and submits the form.
  • Country/state cascading (handle_country_change action) — Fetches states via the REST endpoint limestaff/v1/countries/{code}/states when a country is selected.

If you override this template, include equivalent JavaScript or the pagination and location filters will not function.

4. job-search-pagination.php — Pagination Controls

Renders the page number links and previous/next arrows.

Loaded by: Included from job-search.php

Available Variables

Variable Type Description
$total_pages int Total number of pages.
$current_page int Current active page (1-based).
$has_more_pages bool Whether pages exist after the current one.
$is_archive_page bool Whether this is the virtual jobs archive page.
$base_url string Base URL for building pagination links.

Helper Functions Used

Function Description
limestaff_get_page_list( $total_pages, $current_page, $max_length ) Returns an array of page numbers with 0 representing ellipsis breaks. Defaults to 11 slots maximum.

Pagination Modes

The template renders differently based on $is_archive_page:

  • Archive pages — Uses standard <a href="..."> links with /page/{n}/ URL structure.
  • Shortcode/widget pages — Uses data-page and data-click-action="go-to-page" attributes, handled by the JavaScript in job-search-filters.php.

5. apply-form.php — Application Form

Renders the job application form with name, email, phone, CV upload, custom questions, and CAPTCHA.

Loaded by: LoxoJobView::render_apply_form_template()

Available Variables

Variable Type Description
$form_template_id int The Loxo form template ID (0 if none).
$questions array Array of custom question objects from the form template.
$errors array Array of validation error messages (empty on first load).
$action_url string The form action URL.
$limestaff_job `LoxoJob\ null` The LoxoJob post object, or null if not found.

Action Hooks

Hook Fires Receives
limestaff_apply_form_before_fields Before the default form fields. $limestaff_job
limestaff_apply_form_after_fields After all fields, before the submit button. $limestaff_job

Use these hooks to inject custom fields, disclaimers, or markup:

add_action( 'limestaff_apply_form_before_fields', function( $job ) {
    echo '<p class="form-notice">All fields marked * are required.</p>';
});

add_action( 'limestaff_apply_form_after_fields', function( $job ) {
    echo '<label><input type="checkbox" name="gdpr_consent" required /> I consent to data processing.</label>';
});

Filter Hooks

Filter Description Default
limestaff_apply_form_custom_questions Filter the $questions array before rendering. The raw questions array.
limestaff_question_field_attrs Filter per-question attributes (label, name, required). Original attributes.
limestaff_apply_form_submit_label Filter the submit button text. "Apply Now"
limestaff_cv_is_required Filter whether CV upload is required. true (unless job-level override). 
// Change the submit button label
add_filter( 'limestaff_apply_form_submit_label', function() {
    return 'Submit Application';
});

// Make CV upload optional
add_filter( 'limestaff_cv_is_required', '__return_false' );

Helper Functions

Function Description
limestaff_render_custom_questions( $questions ) Renders all custom question fields. Applies the limestaff_apply_form_custom_questions filter internally.
limestaff_render_question_field( $question ) Renders a single custom question field based on its type.
limestaff_render_captcha_widget() Outputs the CAPTCHA HTML element (reCAPTCHA v2/v3 or Turnstile).
limestaff_render_captcha_scripts() Outputs the CAPTCHA provider JavaScript tags.
limestaff_get_captcha_config() Returns the CAPTCHA config array (includes enabled key).
limestaff_cv_is_required( $job ) Returns whether CV upload is required (filterable).
limestaff_apply_form_submit_label() Returns the submit button label (filterable).
limestaff_apply_form_before_fields( $job ) Fires the limestaff_apply_form_before_fields action.
limestaff_apply_form_after_fields( $job ) Fires the limestaff_apply_form_after_fields action.
limestaff_get_default_phone_region() Returns the default phone region code (e.g. "US").

Per-Field-Type Renderers

For granular control when iterating $questions manually:

Function Field Type Description
limestaff_render_text_field( $name, $required ) Text Single-line text input.
limestaff_render_paragraph_field( $name, $required ) Textarea Multi-line text input.
limestaff_render_single_choice_field( $name, $required, $options ) Radio Radio button group.
limestaff_render_multiple_choice_field( $name, $options ) Checkbox Checkbox group.
limestaff_render_dynamic_field( $name, $required, $question ) Dynamic Adapts based on dynamic_field_type (text, number, date, or hierarchy).
limestaff_render_date_field( $name, $required ) Date Date input.
limestaff_render_number_field( $name, $required ) Number Number input.

Global Helper Functions

These functions are available in all templates and your theme’s functions.php:

Function Description
limestaff_locate_template( $name ) Returns the full path to a template file, checking theme override first.
limestaff_get_view_toggles() Returns the default view toggles array based on global settings.
limestaff_parse_view_toggles( $toggles ) Merges view toggles with global job_meta_visibility settings.
limestaff_get_shown_custom_job_field_data() Returns custom field data configured to be visible in global settings.
limestaff_loxo_currency_id_to_symbol( $id ) Converts a Loxo currency ID to its symbol.
limestaff_strip_inline_styles( $html ) Removes all inline style attributes from HTML.

Tips & Best Practices

Keep overrides minimal

Only override the markup you need to change. The more of the original logic you preserve, the less likely your override is to break on plugin updates.

Always include sub-template calls

If you override job-search.php, make sure you still include the filter and pagination templates:

<?php include limestaff_locate_template( 'job-search-filters' ); ?>
<!-- your custom job cards markup -->
<?php include limestaff_locate_template( 'job-search-pagination' ); ?>

Respect view toggles

Check $render_settings['view_toggles'] before rendering optional meta fields. This ensures that settings configured in the admin panel, Elementor widget, or Bricks widget are honoured in your override.

Preserve form names and nonce fields

The apply form relies on specific input names (applicant_name, applicant_email, applicant_phone, applicant_cv) and a nonce field (apply_job_nonce). Changing these will break form submission.

<?php wp_nonce_field( 'apply_job', 'apply_job_nonce' ); ?>

Preserve data attributes for JavaScript behaviour

The pagination and location filter JavaScript relies on data-click-action, data-page, data-change-action, and data-state-dropdown-id attributes. If you customise the filter or pagination templates, keep these data attributes intact.

Use action hooks instead of full overrides when possible

If you only need to add content before or after the apply form fields, use the action hooks rather than overriding the entire template:

add_action( 'limestaff_apply_form_before_fields', function( $job ) {
    // Your custom markup here
});

Child themes

If you’re using a child theme, place your overrides in child-theme/limestaff/. limestaff_locate_template() checks child themes before parent themes automatically.