The Conductor REST API provides API endpoints for Conductor which allow developers to interact with sites remotely (i.e. via AJAX requests). The Conductor REST API is an extension of the WordPress REST API.

Note: As of April 2018, the Conductor REST API only contains one route for fetching Conductor Widget query results. We have plans to expand the Conductor REST API in the future.

Authentication

At this time there are currently no authentication methods available for use in the Conductor REST API. We have plans in the future to possibly allow for various forms of authentication.

Note: Due to the lack of authentication methods, we’ve provided different ways to disable the Conductor REST API. See the “Conductor Options” and “Conductor Widget Settings” sections below.

Base URL

The base URL for the Conductor REST API is: /conductor/v1/ (e.g. http://website.com/wp-json/conductor/v1/).

If a GET request is made to this URL and the Conductor REST API is enabled, the list of all Conductor REST API endpoints is returned.

Routes

The following is a list of the Conductor REST API routes:

• /conductor/v1/widget/query/{number}/[paged]/

Conductor Options

The Conductor REST API can be enabled or disabled via the “Enable Conductor REST API” setting on the Conductor > Options page.

Enabling or disabling the Conductor REST API via this setting affects the global scope. This means that, if this setting is set to “Off” (disabled), the Conductor REST API will be disabled across the entire website and Conductor REST API route requests will not work as expected.

More granular control is outlined in the “Conductor Widget Settings” section below.

Conductor Widget Settings

Individual Conductor Widgets can be enabled or disabled in the Conductor REST API via the “Enable in Conductor REST API” setting in the Conductor Widget > Advanced Settings section. This setting allows for more granular/specific control.

Enabling or disabling an individual Conductor Widget in the Conductor REST API via this setting only affects that Conductor Widget. This means that, if this setting is unchecked (disabled), only that individual Conductor Widget will be disabled from the Conductor REST API.

The post Conductor REST API appeared first on Conductor.

How Do Conductor Widget AJAX Requests Work?

Conductor Widget AJAX requests work like this:

Conductor first determines if the Conductor Widget has AJAX enabled. If AJAX is enabled on the Conductor Widget, event listeners are added to various Conductor Widget elements (i.e. pagination links). When one of these elements is interacted with (i.e. clicked), a Conductor Widget AJAX request is created.

As of version 1.5.0, Conductor Widgets use the POST request method when making requests to the Conductor REST API.

Technical Details

Conductor Widget AJAX requests will send the following extra data by default:

• conductor_widget (Boolean): Flag to specify whether or not the request originated from a Conductor Widget
  • Default: true
• pagenum_link (string): The current pagenum link; used for the pagination portion of the query results
  • Default: The current URL without any pagination parameters
• is_front_page (Boolean): Flag to specify if the AJAX request originated from the front page; used for the pagination portion of the query results
  • Default: true if is_front_page(), false if not is_front_page()
• is_single (Boolean): Flag to specify if the AJAX request originated from a single post; used for the pagination portion of the query results
  • Default: true if is_single(), false if not is_single()

Conductor Add-Ons

Some Conductor add-ons may add their own extra data to pass along with the AJAX request. See Filtering Add-On  or Query Builder Add-On.

The post Conductor REST API – Conductor Widget AJAX Requests appeared first on Conductor.

This REST API route returns query results (in the form of HTML markup for various Conductor Widget sections) for an individual Conductor Widget based on parameters.

Both GET and POST requests can be made to this Conductor REST API route.

Note: We are utilizing the POST request method due to URL length restrictions (~2000 characters) in various browsers. Conductor add-ons may add extra parameters to this Conductor REST API request and we found that, in some cases, the URL could be close to reaching the length restrictions. See https://stackoverflow.com/a/417184 for more information.

Technical Details

• Type: REST API Route
• URL Parameters:
  • {number} (int): Conductor Widget number (the WordPress widget number assigned to a Conductor Widget); -1 is allowed for the_widget() (see Query Builder Add-On)
  • [paged] (int) (optional): Paged value, current page to return query results for
• Extra Parameters (GET or POST):
  • See: Conductor REST API - Conductor Widget AJAX Requests
• Return Value: JSON object
  • • conductor_widget_before (string): HTML markup for the Conductor Widget before wrapper element
    • conductor_widget_title_before (string): HTML markup for the Conductor Widget title before wrapper element
    • conductor_widget_title_after (string): HTML markup for the Conductor Widget title after wrapper element
    • conductor_widget_content_before (string): HTML markup for the Conductor Widget content before wrapper element
    • conductor_widget_content (string): HTML markup for the Conductor Widget content wrapper element (the main widget content)
    • conductor_widget_content_after (string): HTML markup for the Conductor Widget content after wrapper element
    • conductor_widget_pagination (string): HTML markup for the Conductor Widget pagination wrapper element
    • conductor_widget_after (string): HTML markup for the Conductor Widget after wrapper element
    • number (int, string): Widget number (i.e. 1). In some cases this value may be a string if an add-on has modified the widget number (i.e. Query Builder Add-On)
    • widget_id (string): Widget ID; This is the Conductor Widget ID prefix followed by the widget number (i.e. conductor-widget-1)

Request Validation

When a request is made to this REST API route, Conductor will first verify that the Conductor REST API is enabled. If the Conductor REST API is not enabled, a 404 status will be returned with the following code: conductor_rest_api_disabled.

After Conductor has verified that the Conductor REST API is enabled, it will then check to see that the {number} parameter is set to a valid Conductor Widget number. If the {number} parameter isn’t valid, a 404 status will be returned with the following code: conductor_widget_number_invalid.

If the {number} parameter is valid, Conductor will then check to see if the Conductor Widget is enabled in the Conductor REST API. If the Conductor Widget is not enabled in the Conductor REST API, a 404 status will be returned with the following code: conductor_widget_rest_api_disabled.

If all of the above validation checks have passed, a 200 status code will be returned along with the Conductor Widget query results.

Resources

• • View on GitHub
  • Guide: Conductor Widgets
  • Conductor REST API
  • Conductor REST API – Conductor Widget AJAX Requests

Examples

The following request will return query results for a Conductor Widget with a widget number of 1.

• /wp-json/conductor/v1/widget/query/1/
• http://website.com/wp-json/conductor/v1/widget/query/1/

The following request will return page 4 query results for a Conductor Widget with a widget number of 123.

• /wp-json/conductor/v1/widget/query/123/4/
• http://website.com/wp-json/conductor/v1/widget/query/123/4/

The following is an example of return data from a request to this REST API endpoint. Some of the return data has been truncated.

The following is an example of return data that has been formatted for better readability. It is not technically valid JSON data due to this formatting.

The post /conductor/v1/widget/query/{number}/[paged]/ appeared first on Conductor.

Hierarchy filtering allows the filter options to be narrowed down based on the currently selected filter. This is useful for drilling down content even further by diving into child and grandchild terms.

Please customize the following code to fit your needs. The Filtering add-on will likely support this functionality in a future version which means that this Gist will no longer be necessary at that time.

Place the following code in your child theme’s functions.php file.

The post Hierarchy Filtering appeared first on Conductor.

Place the following code in your child theme’s functions.php file.

The post Enable Legacy Conductor Widget Displays appeared first on Conductor.

The post Changing from Content to Excerpt view in a Conductor widget appeared first on Conductor.

Introduction to Conductor Widgets

Conductor Widgets, like Conductor content layouts, have been a part of Conductor since the initial release. Conductor Widgets are used to create/display blocks of content. Conductor Widgets can be used in any registered sidebar, but are best suited for registered Conductor Sidebar (Widget Areas, Display Areas).

Registering Conductor Widget Displays

Conductor ships with 4 Conductor Widget displays:

• Small (small – 4 Columns, 25% Width)
• Medium (medium – 2 Columns, 50% Width)
• Large (large – 1 Column, 100% Width)
• Custom (flexbox – Variable Columns [using CSS flexbox for display], Up to 6 Columns – see the conductor_widget_max_columns filter documentation page)

The Conductor Display Pack Add-On adds an additional 3 Conductor Widget displays:

• List (list)
• Table (table )
• Grid (grid)

The Conductor Slider Add-On adds an additional 3 Conductor Widget displays:

• Slider: Testimonials (slider-testimonials)
• Slider: Hero  (slider-hero)
• Slider: News (slider-news)

Additional Conductor Widget displays can be registered via the conductor_widget_displays filter. Each display is registered with a unique ID (the array key). Various configuration parameters can be specified such as default values or whether or not this display supports the column customization.

The Conductor Widget Display ID

The Conductor Widget display ID is an important piece of a Conductor Widget. This value helps Conductor determine which display should be loaded.

This ID is added as a CSS class to the widget wrapper element via the conductor_widget_display_content_{$widget_number} action along with other relevant CSS classes. This logic is added in the Conductor_Widget_Query class when an instance is created for a Conductor Widget.

How Conductor Determines Widget Display Design

Determining the widget display design/output will vary from display to display, but generally this is how Conductor Widgets determine the HTML markup:

• When a valid widget instance is detected (i.e. a “many” query or a single query with a valid single piece of content), a new instance of the Conductor_Widget_Query class is created on the front-end.
• The Conductor_Widget_Query class determines the output based on widget instance settings.
• By default, the wrapper and content wrapper elements are added before and after the widget output elements.

Conductor Widget Displays HTML Markup

The default Conductor Widget callback functions are hooked in this order:

• Conductor_Widget_Query::conductor_widget_wrapper() – priority: 1
• Conductor_Widget_Query::conductor_widget_content_wrapper() – priority: 2
• Conductor_Widget_Query::conductor_widget_featured_image() – priority: 10
• Conductor_Widget_Query::conductor_widget_post_title() – priority: 20
• Conductor_Widget_Query::conductor_widget_author_byline() – priority: 30
• Conductor_Widget_Query::conductor_widget_post_content() – priority: 40
• Conductor_Widget_Query::conductor_widget_read_more() – priority: 50
• Conductor_Widget_Query::conductor_widget_content_wrapper_close() – priority: 999
• Conductor_Widget_Query::conductor_widget_wrapper_close() – priority: 1000

Enlarge image for a more detailed view (Note: Markup displayed in the Element Inspector is specific to Baton Pro, not Conductor)

Conductor_Widget_Query::conductor_widget_wrapper()

This callback function outputs the Conductor Widget wrapper opening HTML element.

The default Conductor Widget wrapper element is:

<<?php echo $this->get_content_wrapper_html_element( $post, $instance, $widget, $query ); ?> class="<?php echo apply_filters( 'conductor_widget_content_wrapper_css_classes', 'content post-content conductor-cf', $post, $instance, $widget, $query ); ?><?php echo ( has_post_thumbnail( $post->ID ) ) ? ' has-post-thumbnail content-has-post-thumbnail' : false; ?>">

Conductor_Widget_Query::conductor_widget_content_wrapper()

This callback function outputs the Conductor Widget content wrapper opening HTML element.

The default Conductor Widget content wrapper element is:

<<?php echo $this->get_wrapper_html_element( $post, $instance, $widget, $query  ); ?> class="<?php echo apply_filters( 'conductor_widget_wrapper_css_classes', $this->get_wrapper_css_classes( $post, $instance, $widget ), $post, $instance, $widget, $query ); ?>">

Conductor_Widget_Default_Query::conductor_widget_featured_image()

This callback function outputs the Conductor Widget featured image HTML element.

The default Conductor Widget featured image element is:

// Find the featured image output element data
   $priority = $instance['output_elements']['featured_image'];
   $output = $instance['output'][$priority];

   do_action( 'conductor_widget_featured_image_before', $post, $instance );

   if ( has_post_thumbnail( $post->ID ) ) :
?>
      <div class="thumbnail post-thumbnail featured-image <?php echo ( ! $output['link'] ) ? 'no-link' : false; ?>">
         <?php
            // Output desired featured image size
            if ( ! empty( $instance['post_thumbnails_size'] ) )
               $conductor_thumbnail_size = $instance['post_thumbnails_size'];
            else
               $conductor_thumbnail_size = ( $instance['widget_size'] !== 'small' ) ? $instance['widget_size'] : 'thumbnail';

            $conductor_thumbnail_size = apply_filters( 'conductor_widget_featured_image_size', $conductor_thumbnail_size, $instance, $post );

            // Link featured image to post
            if ( $output['link'] ) :
         ?>
               <a href="proxy.php?url=<?php echo get_permalink( $post->ID ); ?>">
                  <?php echo get_the_post_thumbnail( $post->ID, $conductor_thumbnail_size ); ?>
               </a>
         <?php
            // Just output the featured image
            else:
               echo get_the_post_thumbnail( $post->ID, $conductor_thumbnail_size );
            endif;
         ?>
      </div>
<?php
   endif;

   do_action( 'conductor_widget_featured_image_after', $post, $instance );

Conductor_Widget_Default_Query::conductor_widget_post_title()

This callback function outputs the Conductor Widget post title HTML element.

The default Conductor Widget post title element is:

// Find the post title output element data
   $priority = $instance['output_elements']['post_title'];
   $output = $instance['output'][$priority];

   do_action( 'conductor_widget_post_title_before', $post, $instance );

   $link = ( ! $output['link'] ) ? ' no-link' : false;
?>
   <h2 class="<?php echo apply_filters( 'conductor_widget_post_title_css_classes', 'post-title entry-title' . $link, $output ); ?>">
      <?php
         // Link post title to post
         if ( $output['link'] ) :
      ?>
            <a href="proxy.php?url=<?php echo get_permalink( $post->ID ); ?>">
               <?php echo get_the_title( $post->ID ); ?>
            </a>
      <?php
         // Just output the post title
         else:
            echo get_the_title( $post->ID );
         endif;
      ?>
   </h2>
<?php
   do_action( 'conductor_widget_post_title_after', $post, $instance );

Conductor_Widget_Default_Query::conductor_widget_author_byline()

This callback function outputs the Conductor Widget author byline HTML element.

The default Conductor Widget author byline element is:

do_action( 'conductor_widget_author_byline_before', $post, $instance );
?>
   <p class="post-author"><?php printf( __( 'Posted by <a href="proxy.php?url=%1$s">%2$s</a> on %3$s', 'conductor' ) , get_author_posts_url( get_the_author_meta( 'ID' , $post->post_author ) ), get_the_author_meta( 'display_name', $post->post_author ), get_the_time( 'F jS, Y', $post ) ); ?></p>
<?php
   do_action( 'conductor_widget_author_byline_after', $post, $instance );

Conductor_Widget_Default_Query::conductor_widget_post_content()

This callback function outputs the Conductor Widget post content HTML element.

The default Conductor Widget post content element is:

do_action( 'conductor_widget_post_content_before', $post, $instance );

// Determine which type of content to output
switch ( $instance['content_display_type'] ) {
   // Excerpt - the_excerpt()
   case 'excerpt':
      echo $this->get_excerpt_by_id( $post, $instance['excerpt_length'] );
   break;

   // the_content()
   case 'content':
   default:
      echo $this->get_content_by_id( $post );
   break;
}

do_action( 'conductor_widget_post_content_after', $post, $instance );

Conductor_Widget_Default_Query::conductor_widget_read_more()

This callback function outputs the Conductor Widget read more HTML element.

The default Conductor Widget read more element is:

// Find the read more output element data
   $priority = $instance['output_elements']['read_more'];
   $output = $instance['output'][$priority];

   do_action( 'conductor_widget_read_more_before', $post, $instance );

   // Link read more to post
   if ( $output['link'] ) :
?>
      <a class="more read-more more-link" href="proxy.php?url=<?php echo get_permalink( $post->ID ); ?>">
         <?php echo $output['label']; ?>
      </a>
<?php
   // Just output the read more
   else:
      echo $output['label'];
   endif;

   do_action( 'conductor_widget_read_more_after', $post, $instance );

Conductor_Widget_Query::conductor_widget_content_wrapper_close()

This callback function outputs the Conductor Widget content wrapper closing HTML element.

The default Conductor Widget content wrapper closing element is:

</<?php echo $this->get_content_wrapper_html_element( $post, $instance, $widget, $query ); ?>>

Conductor_Widget_Query::conductor_widget_wrapper_close()

This callback function outputs the Conductor Widget wrapper closing HTML element.

The default Conductor Widget wrapper closing element is:

</<?php echo $this->get_wrapper_html_element( $post, $instance, $widget, $query ); ?>>

View all on GitHub

Conductor Widget CSS Markup

The following is a list of CSS classes used throughout Conductor Widgets categorized by the elements which they are used on:

• Conductor_Widget_Query::conductor_widget_wrapper() Element
  • get_post_class() CSS Classes
  • conductor-widget
  • {$widget_size} – e.g. large
  • “Many” Queries:
    • conductor-widget-{$widget_size} – e.g. conductor-widget-large
    • Even Pieces of Content:
      • conductor-widget-even
      • conductor-widget-{$widget_size}-even – e.g. conductor-widget-large-even
    • Odd Pieces of Content:
      • conductor-widget-odd
      • conductor-widget-{$widget_size}-odd – e.g. conductor-widget-large-odd
  • Single Queries:
    • conductor-widget-single
    • conductor-widget-single-{$widget_size} – e.g. conductor-widget-single-large
  • {$instance_css_class} – e.g. my-custom-class
• Conductor_Widget_Query::conductor_widget_content_wrapper() Element
  • content
  • post-content
  • conductor-cf
• Conductor_Widget_Query::conductor_widget_featured_image() Element
  • thumbnail
  • post-thumbnail
  • featured-image
  • no-link (if the output element is set to not link to the content piece)
• Conductor_Widget_Query::conductor_widget_post_title() Element
  • post-title
  • entry-title
  • no-link (if the output element is set to not link to the content piece)
• Conductor_Widget_Query::conductor_widget_author_byline() Element
  • post-author
• Conductor_Widget_Query::conductor_widget_post_content() Element
  • None
• Conductor_Widget_Query::conductor_widget_read_more() Element – if the output element is set to not link to the content piece
  • more
  • read-more
  • more-link

The following is a list of CSS classes used on Conductor Widgets with displays that support flexbox (in addition to the CSS classes above):

• before_widget Element
  • “Many” Queries:
    • conductor-widget-wrap
    • conductor-row
    • conductor-widget-row
    • conductor-flex
    • conductor-widget-flex
    • conductor-row-{$instance_columns}-columns
    • conductor-widget-row-{$instance_columns}-columns
    • conductor-flex-{$instance_columns}-columns
    • conductor-widget-flex-{$instance_columns}-columns
    • conductor-{$instance_columns}-columns
    • conductor-widget-{$instance_columns}-columns
  • Single Queries
    • If Multiple Single Queries with the Same Column Number Exist Together (one after another in the same sidebar):
      • conductor-widget-single-flexbox-wrap
• Conductor_Widget_Query::conductor_widget_wrapper() Element
  • conductor-col
  • conductor-col-{$column_number}

View all on GitHub

Resources

• Understanding the Conductor Template System
• Guide: Conductor Content Layouts
• Conductor Widget Overview
• Adding a Conductor Widget

The post Conductor Widgets appeared first on Conductor.

This function is a helper function which loads a Conductor template part based on parameters. Alternatively extra parameters (data), and WordPress global variables can be passed to the template part (see examples below).

Conductor will look in the active theme’s Conductor template path directory first. If a template part is found in the active theme, it will be loaded. Otherwise, the “fallback” (default) template part will be used if it exists (in the /conductor/templates/ directory).

Prior to the template part being loaded, the template name is passed to the conductor_get_template_part filter.

Note: If a template is not found, this function will fail silently.

Technical Details

• Type: Function
• Parameters:
  • $slug (string; required): The slug portion of the template part (i.e. if the template part is named sidebar-custom.php, the "sidebar" portion is the slug)
  • $name (string): The name portion of the template part (i.e. if the template part is named sidebar-custom.php, the "custom" portion is the name)
  • $data (array): Optional data to pass along to the template part; if this parameter is not empty (and is an array), it is passed to the conductor_get_template_part_data filter
  • $wp_globals (Boolean): Whether or not to use WordPress global variables; these include - global $posts, $post, $wp_did_header, $wp_query, $wp_rewrite, $wpdb, $wp_version, $wp, $id, $comment, $user_ID;
  • $require_once (Boolean): Whether or not to use require_once() to load the template part, otherwise require() is used
• Return Value: None

Resources

• View on GitHub
• Conductor Content Layouts
• Conductor::theme_template_path()
• Conductor_Template_Loader::template_include()

Examples

The following example demonstrates how to use conductor_get_template_part() in a custom Conductor content layout template.

The post conductor_get_template_part() appeared first on Conductor.