The Relationship field can store relationships to one or more related items. It offers many different types of input options as well as the ability to provide a custom list of choices or choose an existing WordPress object to pull data from.
Contents
Quick Start
- Fill out the Basic Field Settings (Label, Description, and Field Name)
- Select Field Type: Relationship.
- Click Save New Field (or Save Field if you’re updating an existing field) to save your field configuration.
Settings
- Selection Type
This determines which Input Types can be used. The available options are:- Single Select
- Input Type
These input types are available for Single Select. Available options are:- Drop Down
- Radio Buttons
- Autocomplete
- List View (with reordering)
- Input Type
- Multiple Select
- Input Type
These input types are available for Multiple Select. Available options are:- Checkboxes
- Multi Select (basic selection)
- Autocomplete
- List View (with reordering)
- Display Format
These formats are available for Multiple Select. Available options are:- Item 1, Item 2, and Item 3
- Item 1, Item 2 and Item 3
- Custom separator (without “and”)
- Display Format Separator
Used as separator for front-end display. This also turns off the “and” portion of the formatting. Default is “, “
- Display Format Separator
- Selection Limit
You can choose how many selections to allow for Multiple Select. Default is “0” for no limit, but you can enter 1 or more to limit the number of items that can be selected.
- Input Type
- Single Select
- Allow Add New
Allow new related records to be created in a modal window within the same form screen. This helps speed up content entry and is available for any input type. It is compatible with relationships with Post Types, Taxonomies, Users, or Advanced Content Types. - For Autocomplete fields
- Taggable
When using Autocomplete input type and Allow Add New is disabled, you can allow new values to be entered directly into the Autocomplete field for supported objects. It is compatible with relationships with Post Types, Taxonomies, Users, or Advanced Content Types.
- Taggable
- For List View fields
- Show Icons
This will show the Featured Image (if related to a post type) or the content type Icon. This is useful for content entry because it helps to differentiate between different related items. - Show Edit Links
Allow related records to be edited in a modal window within the same form screen. This helps speed up content updates. It is compatible with relationships with Post Types, Taxonomies, Users, or Advanced Content Types. - Show View Links
Allow related records to be viewed in a new window. This helps to preview related content more easily. It is compatible with relationships with Post Types, Taxonomies, Users, or Advanced Content Types.
- Show Icons
- For Drop Down fields
- Default Select Text
This is the text used for the default “no selection” dropdown item. If left empty, it will default to “– Select One –“.
- Default Select Text
- For Relationships to Tables (when the Advanced Relationships Component is enabled)
- Table ID Column
This is the ID column name used to keep track of the relationship. - Table Index Column
This is the index column name used to show the label of the related row.
- Table ID Column
- For Relationships to Post Types
- Limit list by Post Status
You can choose to limit Posts available for selection by one or more specific post status
- Limit list by Post Status
- For Relationships to Users
- Limit list by Role(s)
You can choose to limit Users available for selection by specific role(s).
- Limit list by Role(s)
- Display Field in Selection List
This is the name of a field on the related object to reference, example:{@post_title}
. The default will be the index field detected on the related object (Post Title, Term Name, User Display Name, etc). - Customized WHERE
This allows you to further restrict the related items available for selection with a custom MySQL WHERE clause. See examples in find() ‘where’ parameter. - Customized ORDER BY
This allows you to further change the order of the related items available for selection with a custom MySQL ORDER BY clause. See examples in find() ‘where’ parameter. - Customized GROUP BY
This allows you to further change the related items available for selection with a custom MySQL GROUP BY clause. See examples in find() ‘where’ parameter.
How to Display
When displaying relationships, it will always display the label/title of the related item. When using multiple select, Pods will automatically output the list in a readable format using the Oxford Comma like: Option One, Option Two, and Option Three.
By default, Pods will not link to the related object URLs when displaying. If you want to do this, you can look at field() or using [each].
You can also traverse into any related item’s data by following field() traversal notation.
Display with a Shortcode
[pods field="my_relationship_field"]
Display with PHP: pods_field_display()
<?php echo pods_field_display( 'my_relationship_field' );
Display with PHP: $pod->display()
<?php $pod = pods(); echo $pod->display( 'my_relationship_field' );