What is AddBySearch?
AddBySearch is a Taco add-on that allows you to easily assign relationships to other posts as well as assign an order.
What else?
For instance, you have a custom post type of "Employee" and another of "Emergency Contact", each with their own respective fields. What if you wanted to assign many emergency contacts to an employee? This could be done straight from code, but this would require hardcoding and assigning relationships by "ID" which has no meaning. This is no task for someone without any knowledge of code.
It's also fair to say this plugin has other great features included in the UI. Here's a quick breakdown.
- Add posts by searching or showing all of a post type that you choose to show.
- Order posts the way you want by an easy to use drag-n-drop interface.
-
Delete a post that has a relationship. Don't worry, you're covered.
It will automatically be removed from any relationships. - What if you just want the ordering mechanism? There is a setting just for this.
- If you need to limit the value to one, you can do that too.
Installation
Composer is the preferred method for installing AddBySearch. In order to install AddBySearch, you must first install Taco. Go here for more information:
Taco Installation instructions
Add the below to your composer file.
{ "require": { "tacowordpress/addbysearch": "dev-master" } }
In your functions.php file, make sure to initialize Taco followed by AddBySearch.
wordpress/wp-content/your-theme/functions.php
// Initialize Taco \Taco\Loader::init(); // Initialize AddBySearch \AddBySearch\Loader::init();
Dependencies
- Taco >= 0.2.3
- WordPress >= 3.3
- PHP >= 5.3
Setup
Defining a custom field as an addbysearch field
This plugin relies on Taco (Custom Posts) and is configured through the getFields method.
Here's how to use it.
<?php
/*
Plugin Name: Employee
Version: 1.0
Description: Employee Post Type
*/
class Employee extends \Taco\Post
{
public function getFields()
{
return array(
'employee_friends' => array(
'type' => 'text',
'class' => 'addbysearch',
'data-post-type' => 'Employee'
)
);
}
}
The above code will ouput an autocomplete search seen in the next section below.
Using the Autocomplete Search
Limiting the field to accepting only one value.
just use: 'data-single-value'=> true
This will prevent admin users from picking more values from the list until they remove what's already there.
<?php
public function getFields()
{
return array(
'employee_boss' => array(
'type' => 'text',
'class' => 'addbysearch',
'data-post-type' => 'Employee',
'data-single-value' => true
)
);
}
Disabling the "Show All" button
If for some reason you wish to disable the "Show All" button, you can set 'data-disable-show-all' => true in the field definition of the getFields() method.
Ordering Posts
In many cases you may just want the ordering mechanism. The addition of 'data-order-only' => true makes this possible.
<?php
/*
Plugin Name: Employee
Version: 1.0
Description: Employee Post Type
*/
class Employee extends \Taco\Post
{
public function getFields()
{
return array(
'employee_friends' => array(
'type' => 'text',
'class' => 'addbysearch',
'data-post-type' => 'Employee',
'data-order-only' => true
)
);
}
}
Using AddBySearch in your template
<?php
global $post;
// load the current post (post type of department)
$department = \Taco\Post\Factory::create($post);
// get the department's list of employees that have been custom picked and ordered by the admin
$employees = \AddBySearch\AddBySearch::getPostsFromOrder(
$department->get('employees')
);
if(Arr::iterable($employees)) {
foreach($employees as $employee) {
echo $employee->getTheTitle();
}
}
Args for the method \AddBySearch::getPostsFromOrder()
AddBySearch::getPostsFromOrder(
$string_order = '',
$reverse = true,
$is_term = false,
$taxonomy = null
)
Explanation of arguments
- $string_order String A comma seperated list of post ids
- $reverse Bool Should the list of posts be reversed?
- $is_term Bool Are we getting a taxonomy term instead of a post?
- $taxonomy String If the last argument was set to true, then this argument is the taxonomy to use.
Defining your own methods.
At some point, you may want the data to be filtered differently in the results that show up. For instance. What if you want to show employees under the taxonomy "employee-type" that are assigned the term "human-resources"?
<?php
/*
Plugin Name: Department
Version: 1.0
Description: Department Post Type
*/
class Department extends \Taco\Post
{
public function getFields()
{
return array(
'employees_human_resources' => array(
'type' => 'text',
'class' => 'addbysearch',
'data-post-type' => 'Department::getHumanResourcesEmployeePairs',
'data-order-only' => true
)
);
}
public function getHumanResourcesEmployeesPairs()
{
$employees = (new Employee)->getByTerm('employee-type', 'human-resources');
return array_combine(
Collection::pluck($employees, 'ID'),
Collection::pluck($employees, 'post_title')
);
}
}
The above is just short example, but I think you get the idea.
Note: When using a custom method for getting posts, make sure it returns an array where the key is the post id and the value is a descriptor such as the title.
Custom Titles
Changing the title is easy. Below is an example of how to add the post id to the title.
<?php
class Employee extends \Taco\Post
{
public function getFields()
{
return array(
'employees' => array(
'type' => 'text',
'class' => 'addbysearch',
'data-post-type' => 'Employee::getCustomPairs',
)
);
}
public function getCustomPairs()
{
$posts = Employee::getPairs();
return array_map(function($post, $id) {
return $id. ' | '.$post;
}, $posts, array_keys($posts));
}
}
License
AddBySearch is open source software released under the MIT License. You can View AddBySearch on GitHub to view the license information and to contribute to the project.